openapi: 3.0.3
info:
    title: Ponitor Messaging API
    version: 1.1.0
    description: |-
        Send an SMS, a WhatsApp message or an email, and see what happened to it. Each channel has
        its own paths: `/sms`, `/whatsapp` and `/emails`.

        Every message and email has your own `externalId`. Sending the same `externalId` again on
        the same channel returns what it made the first time. You aren't charged twice.

        The older `/messages` paths are deprecated. They keep working as they always have.
    contact:
        name: Ponitor
        url: https://www.ponitor.com
        email: info@ponitor.com
    license:
        name: MIT License
        url: https://opensource.org/licenses/MIT

servers:
    - url: https://api.ponitor.com/messaging/v1
      description: Live
    - url: https://sandbox-api.ponitor.com/messaging/v1
      description: Sandbox

tags:
    - name: sms
      description: Send an SMS and look one up
    - name: whatsapp
      description: Send a WhatsApp message, look one up and mark one read
    - name: email
      description: Send an email and look one up
    - name: messages
      description: The older paths, deprecated. Use /sms and /whatsapp
    - name: system
      description: System and healthcheck operations

paths:
    /sms:
        post:
            summary: Send an SMS
            description: |-
                Sends one SMS to one number. It's charged and queued at once (`201`, status
                `QUEUED`). Follow it with `GET /sms/{id}` or the `message.*` webhook events.

                A request with an `externalId` you already used on an SMS returns the original
                with `200`. One already used on a WhatsApp message is refused with `409`.
            operationId: sendSms
            tags: [sms]
            security:
                - oauth2: []
                - apiKeyAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SmsRequest'
            responses:
                '201':
                    description: The SMS, charged and queued
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SmsMessageResponse'
                            examples:
                                queued:
                                    $ref: '#/components/examples/SmsQueued'
                '200':
                    description: An `externalId` you had already used on an SMS; this is the original
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SmsMessageResponse'
                            examples:
                                queued:
                                    $ref: '#/components/examples/SmsQueued'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '409':
                    $ref: '#/components/responses/409Conflict'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /sms/{id}:
        parameters:
            - $ref: '#/components/parameters/idParam'
        get:
            summary: Get an SMS
            description: |-
                Gets an SMS you sent or received, with its status now. The id of a WhatsApp
                message answers `404`, as an id that doesn't exist does.
            operationId: getSms
            tags: [sms]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: The SMS
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SmsMessageResponse'
                            examples:
                                delivered:
                                    $ref: '#/components/examples/SmsDelivered'
                                undelivered:
                                    $ref: '#/components/examples/SmsUndelivered'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /whatsapp:
        post:
            summary: Send a WhatsApp message
            description: |-
                Sends one template or reply to one number, in `text`, or in the field named after
                the message's type. It's charged and queued at once (`201`, status `QUEUED`).
                Follow it with `GET /whatsapp/{id}` or the `message.*` webhook events.

                `smsFallback` sends an SMS if the number turns out not to be on WhatsApp. Once it
                has gone, `smsFallback.messageId` on this message is the id to read it with at
                `GET /sms/{id}`.

                A request with an `externalId` you already used on a WhatsApp message returns the
                original with `200`. One already used on an SMS is refused with `409`.
            operationId: sendWhatsApp
            tags: [whatsapp]
            security:
                - oauth2: []
                - apiKeyAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WhatsAppRequest'
            responses:
                '201':
                    description: The message, charged and queued
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppMessageResponse'
                            examples:
                                text:
                                    $ref: '#/components/examples/WhatsAppText'
                                template:
                                    $ref: '#/components/examples/WhatsAppTemplate'
                '200':
                    description: An `externalId` you had already used on a WhatsApp message; this is the original
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppMessageResponse'
                            examples:
                                text:
                                    $ref: '#/components/examples/WhatsAppText'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '409':
                    $ref: '#/components/responses/409Conflict'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /whatsapp/{id}:
        parameters:
            - $ref: '#/components/parameters/idParam'
        get:
            summary: Get a WhatsApp message
            description: |-
                Gets a WhatsApp message you sent or received, with its status now. The id of an
                SMS answers `404`, as an id that doesn't exist does.
            operationId: getWhatsApp
            tags: [whatsapp]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: The message
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppMessageResponse'
                            examples:
                                template:
                                    $ref: '#/components/examples/WhatsAppTemplate'
                                received:
                                    $ref: '#/components/examples/WhatsAppReceived'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /whatsapp/{id}/read:
        parameters:
            - $ref: '#/components/parameters/idParam'
        post:
            summary: Mark a message read
            description: |-
                Marks a WhatsApp message a customer sent as read (blue ticks) and shows them
                "typing…" until your reply is delivered or 25 seconds pass. It isn't charged.
            operationId: markWhatsAppRead
            tags: [whatsapp]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: Marked read
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppMessageResponse'
                            examples:
                                received:
                                    $ref: '#/components/examples/WhatsAppReceived'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /emails:
        post:
            summary: Send an email
            description: |-
                Sends one email to one address, drawn from your template whose handle is
                `template`, with `values` filled in. It goes from your sender whose address is
                `from`, or your default sender when you leave `from` out.

                The email is charged and queued at once (`201`, status `QUEUED`), then sent within
                seconds. Follow it with `GET /emails/{id}` or the `email.*` webhook events.

                - `QUEUED` means it's charged and waiting to go out.
                - `SENT` means it's on its way to the inbox.
                - `DELIVERED` means the recipient's mail server accepted it.
                - `DELAYED` means the recipient's mail server hasn't taken it yet. It's tried again.
                - `BOUNCED` means the address doesn't exist or wouldn't take it. It was sent, so it
                  isn't refunded.
                - `COMPLAINED` means the recipient marked it as spam.
                - `FAILED` means it couldn't be sent. Its cost was refunded, and `failureReason` says
                  why.

                A request with an `externalId` you already used returns the original email with
                `200`, whatever else it says.

                If too many of your emails bounce or are marked as spam, your team's sending is
                paused. Every send is then refused with `403` (`E02017`) until Ponitor resumes it.
            operationId: sendEmail
            tags: [email]
            security:
                - oauth2: []
                - apiKeyAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/EmailRequest'
                        examples:
                            code:
                                summary: A verification code, from your default sender
                                value:
                                    to: ada@example.com
                                    template: verification-code
                                    values:
                                        code: '482913'
                                    externalId: signup-8812
                            receipt:
                                summary: A receipt, from a sender you name
                                value:
                                    to: kofi@example.com
                                    template: receipt
                                    from: billing@mail.example.com
                                    values:
                                        first_name: Kofi
                                        amount: $25.00
                                    externalId: order-8842
            responses:
                '201':
                    description: The email, charged and queued
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailResponse'
                            examples:
                                queued:
                                    $ref: '#/components/examples/EmailQueued'
                '200':
                    description: An `externalId` you had already used; this is the original email
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailResponse'
                            examples:
                                queued:
                                    $ref: '#/components/examples/EmailQueued'
                '400':
                    description: |-
                        Invalid input (`E01001`); a variable without a value
                        (`"Give a value for {{code}}."`); no default sender
                        (`"Add a sender under Email › Domains first."`); a sender whose domain isn't
                        verified; `workspace` in the request (email is your team's); or not enough
                        account balance (`E03001`).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    description: |-
                        Your team has not been verified yet (`E02010`), or its email sending is
                        paused (`E02017`).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '404':
                    description: |-
                        No template has that handle
                        (`"No template has the handle verification-code. Each template's handle is
                        under Email › Templates."`), or `from` isn't one of your senders.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '500':
                    $ref: '#/components/responses/500ServerError'
                '503':
                    description: Email isn't available for a moment. Nothing was sent or charged.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    /emails/{id}:
        parameters:
            - $ref: '#/components/parameters/emailIdParam'
        get:
            summary: Get an email
            description: |-
                Returns an email, its status now, and everything that happened to it, oldest first
                (`events`). Any of your team's emails, whether sent with this API or from the web
                app.
            operationId: getEmail
            tags: [email]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: The email
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmailWithEventsResponse'
                            examples:
                                delivered:
                                    $ref: '#/components/examples/EmailDelivered'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /messages:
        post:
            summary: Create and send a message
            deprecated: true
            description: Deprecated. Use `POST /sms` or `POST /whatsapp`. It keeps working as it always has.
            operationId: createMessage
            tags: [messages]
            security:
                - oauth2: []
                - apiKeyAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [sender, channel, recipient, externalId, content]
                            properties:
                                sender:
                                    type: string
                                    minLength: 2
                                    maxLength: 11
                                    example: 'PONITOR'
                                channel:
                                    $ref: '#/components/schemas/Channel'
                                recipient:
                                    type: string
                                    pattern: '^[1-9]\d{9,14}$'
                                    example: '231880900900'
                                externalId:
                                    type: string
                                    example: 'INV-2025-0001'
                                content:
                                    $ref: '#/components/schemas/MessageContent'
            responses:
                '201':
                    description: Message successfully sent
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Message'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /messages/{id}:
        parameters:
            - $ref: '#/components/parameters/idParam'
        get:
            summary: Retrieve message details
            deprecated: true
            description: Deprecated. Use `GET /sms/{id}` or `GET /whatsapp/{id}`. It keeps reading every SMS and WhatsApp message.
            operationId: fetchMessage
            tags: [messages]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: Message found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Message'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '404':
                    $ref: '#/components/responses/404NotFound'

    /messages/{id}/read:
        parameters:
            - $ref: '#/components/parameters/idParam'
        post:
            summary: Mark a message read
            deprecated: true
            description: Deprecated. Use `POST /whatsapp/{id}/read`. It keeps working as it always has.
            operationId: markMessageRead
            tags: [messages]
            security:
                - oauth2: []
                - apiKeyAuth: []
            responses:
                '200':
                    description: Marked read
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Message'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    $ref: '#/components/responses/403Forbidden'
                '404':
                    $ref: '#/components/responses/404NotFound'

    /healthchecks:
        get:
            summary: API health status
            description: Returns API uptime and operational status.
            operationId: healthStatus
            tags: [system]
            responses:
                '200':
                    description: API is operational
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HealthResponse'

components:
    parameters:
        idParam:
            name: id
            in: path
            required: true
            description: Unique message ID
            schema:
                type: string
                format: uuid
        emailIdParam:
            name: id
            in: path
            required: true
            description: The email's id, returned when it was sent
            schema:
                type: string
                format: uuid

    schemas:
        Channel:
            type: string
            enum: [SMS, WHATSAPP, MESSENGER]
            example: SMS

        SMS:
            type: string
            example: 'Hello from Ponitor!'

        WHATSAPP:
            type: object
            required: [type, text]
            properties:
                type:
                    type: string
                    enum: [text]
                    example: text
                text:
                    type: object
                    properties:
                        body:
                            type: string
                            example: 'Hello via WhatsApp!'

        MessageContent:
            oneOf:
                - $ref: '#/components/schemas/SMS'
                - $ref: '#/components/schemas/WHATSAPP'
            example: 'Your OTP is 456789'

        Message:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                sender:
                    type: string
                    example: 'PONITOR'
                recipient:
                    type: string
                    example: '231880900900'
                content:
                    $ref: '#/components/schemas/MessageContent'
                status:
                    type: string
                    description: >-
                        QUEUED until the network accepts it, then SENT, then DELIVERED, EXPIRED,
                        UNDELIVERED or UNKNOWN. FAILED means the network never accepted it (not billed).
                    enum: [QUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN, FAILED]
                    example: DELIVERED
                failedReason:
                    type: string
                    nullable: true
                    description: Why the message was not delivered, in plain language. Set for EXPIRED, UNDELIVERED and FAILED.
                    example: 'Recipient unreachable: phone was off or out of coverage until the message expired'
                failureCode:
                    type: string
                    nullable: true
                    description: >-
                        Why the message was not delivered, as a code from the error reference
                        (docs.ponitor.com/api/errors), such as E11001. Branch on this, not on
                        failedReason. Set for EXPIRED, UNDELIVERED and FAILED.
                    pattern: '^E11[0-9]{3}$'
                    example: E11001
                credits:
                    type: number
                    example: 1
                channel:
                    $ref: '#/components/schemas/Channel'
                direction:
                    type: string
                    enum: [INBOUND, OUTBOUND]
                    example: OUTBOUND
                externalId:
                    type: string
                    example: 'INV-2025-0001'
                conversationId:
                    type: string
                    format: uuid
                    nullable: true
                createdAt:
                    type: string
                    format: date-time
                    example: '2025-10-26T12:45:30Z'

        SmsRequest:
            type: object
            additionalProperties: false
            required: [sender, recipient, externalId]
            description: |-
                Send the message as `text`, or a one-time code as `template` (one, not both).
            properties:
                sender:
                    type: string
                    minLength: 2
                    maxLength: 11
                    description: Your approved Sender ID or Short Code, as the app shows it.
                    example: PonitorMFI
                recipient:
                    type: string
                    description: The phone number, in international format, with or without the +.
                    example: '+231770000000'
                workspace:
                    type: string
                    description: The handle of the workspace to send from and charge. Leave it out for Main.
                    example: gbarnga-branch
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: |-
                        Your own reference, unique within your team. Sending it again on an SMS
                        returns the original. Nothing new is sent or charged.
                    example: otp-58213
                text:
                    type: string
                    minLength: 2
                    maxLength: 640
                    description: The message.
                    example: Your Ponitor MFI code is 482910.
                template:
                    $ref: '#/components/schemas/SmsOtpTemplate'

        SmsOtpTemplate:
            type: object
            additionalProperties: false
            required: [id, parameters]
            description: |-
                A one-time code (OTP). Ponitor writes the message in the wording Orange and MTN
                let through: "Hello! Your verification code is 482910. Valid for 10 minutes."
                It goes ahead of your other SMS. See One-time codes in the SMS guides.
            properties:
                id:
                    type: string
                    enum: [otp]
                    description: The template. `otp` is the only one an SMS can be sent with.
                parameters:
                    type: object
                    additionalProperties: false
                    required: [code, duration]
                    properties:
                        code:
                            type: string
                            pattern: '^[0-9]{4,10}$'
                            description: The code, 4 to 10 digits, as text so leading zeros stay.
                            example: '482910'
                        duration:
                            type: string
                            minLength: 1
                            maxLength: 20
                            description: How long the code works, as the customer should read it. Put in as sent, on one line.
                            example: 10 minutes

        WhatsAppRequest:
            type: object
            additionalProperties: false
            required: [sender, recipient, externalId]
            description: |-
                Send the message as one of `text`, `image`, `video`, `audio`, `document`, `sticker`,
                `location`, `contacts` or `template`. `buttons`, `list` or `link` go with `text`.
            properties:
                sender:
                    type: string
                    description: Your WhatsApp number, as the app shows it.
                    example: '+231770000000'
                recipient:
                    type: string
                    description: |-
                        The phone number, in international format, with or without the +, or the id
                        WhatsApp gives someone who hides their number (LR.1349…), as a received
                        message's sender.
                    example: '+231880000000'
                workspace:
                    type: string
                    description: The handle of the workspace to send from and charge. Leave it out for Main.
                    example: gbarnga-branch
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: |-
                        Your own reference, unique within your team. Sending it again on a WhatsApp
                        message returns the original. Nothing new is sent or charged.
                    example: reply-58213
                text:
                    type: string
                    minLength: 2
                    maxLength: 4096
                    description: The message's text, inside the 24-hour window.
                    example: Thanks for your payment. Your receipt is on its way.
                previewUrl:
                    type: boolean
                    description: With text. Whether WhatsApp shows a preview of a link in it.
                image:
                    $ref: '#/components/schemas/CaptionedFile'
                video:
                    $ref: '#/components/schemas/CaptionedFile'
                audio:
                    $ref: '#/components/schemas/FileLink'
                document:
                    type: object
                    additionalProperties: false
                    required: [url]
                    properties:
                        url:
                            type: string
                            format: uri
                        filename:
                            type: string
                            maxLength: 240
                            description: Kept for your records. The customer doesn't see it.
                        caption:
                            type: string
                            maxLength: 1024
                            description: Sent as its own text once the document is delivered.
                sticker:
                    $ref: '#/components/schemas/FileLink'
                location:
                    $ref: '#/components/schemas/Location'
                contacts:
                    type: array
                    minItems: 1
                    maxItems: 10
                    items:
                        $ref: '#/components/schemas/ContactCard'
                template:
                    type: object
                    additionalProperties: false
                    required: [id]
                    description: An approved template, by the Template ID the app shows.
                    properties:
                        id:
                            type: string
                            format: uuid
                        body:
                            type: array
                            maxItems: 20
                            description: The values for the message's {{1}}, {{2}} and so on, in order.
                            items:
                                type: string
                                minLength: 1
                                maxLength: 1024
                        buttons:
                            type: array
                            maxItems: 10
                            description: The values for its buttons' placeholders, in order.
                            items:
                                type: string
                                minLength: 1
                                maxLength: 1024
                buttons:
                    type: array
                    minItems: 1
                    maxItems: 3
                    description: With text. Reply buttons.
                    items:
                        $ref: '#/components/schemas/ReplyButton'
                list:
                    $ref: '#/components/schemas/ReplyList'
                link:
                    $ref: '#/components/schemas/LinkButton'
                smsFallback:
                    type: object
                    additionalProperties: false
                    required: [sender, text]
                    description: The SMS to send if the number turns out not to be on WhatsApp.
                    properties:
                        sender:
                            type: string
                            description: Your approved SMS Sender ID.
                            example: PonitorMFI
                        text:
                            type: string
                            maxLength: 640
                            example: Your Ponitor MFI receipt is ready.

        CaptionedFile:
            type: object
            additionalProperties: false
            required: [url]
            properties:
                url:
                    type: string
                    format: uri
                caption:
                    type: string
                    maxLength: 1024

        FileLink:
            type: object
            additionalProperties: false
            required: [url]
            properties:
                url:
                    type: string
                    format: uri

        Location:
            type: object
            required: [latitude, longitude]
            properties:
                latitude:
                    type: number
                    minimum: -90
                    maximum: 90
                longitude:
                    type: number
                    minimum: -180
                    maximum: 180
                name:
                    type: string
                    nullable: true
                address:
                    type: string
                    nullable: true

        ContactCard:
            type: object
            required: [name]
            properties:
                name:
                    type: string
                    maxLength: 100
                phones:
                    type: array
                    maxItems: 5
                    items:
                        type: string
                emails:
                    type: array
                    maxItems: 5
                    items:
                        type: string
                        format: email

        ReplyButton:
            type: object
            required: [id, title]
            properties:
                id:
                    type: string
                    maxLength: 128
                title:
                    type: string
                    maxLength: 20

        ReplyList:
            type: object
            required: [button, items]
            description: With text. A list the customer picks a row from.
            properties:
                button:
                    type: string
                    maxLength: 20
                items:
                    type: array
                    minItems: 1
                    maxItems: 10
                    items:
                        type: object
                        required: [id, title, description]
                        properties:
                            id:
                                type: string
                                maxLength: 128
                            title:
                                type: string
                                maxLength: 24
                            description:
                                type: string
                                maxLength: 72

        LinkButton:
            type: object
            required: [title, url]
            description: With text. One button that opens an https link.
            properties:
                title:
                    type: string
                    maxLength: 20
                url:
                    type: string
                    format: uri

        ShapedFile:
            type: object
            description: A file in a message. A received file's url works for an hour.
            properties:
                url:
                    type: string
                    format: uri
                caption:
                    type: string
                mimeType:
                    type: string
                filename:
                    type: string
                size:
                    type: integer

        SmsMessage:
            type: object
            description: An SMS you sent or received. Every field is always there.
            required: [id, channel, direction, sender, recipient, text, status, cost, failureReason, failureCode, externalId, conversationId, createdAt, updatedAt]
            properties:
                id:
                    type: string
                    format: uuid
                    example: 6c22adb9-8d60-45aa-a412-8d930cd6b334
                channel:
                    type: string
                    enum: [SMS]
                    example: SMS
                direction:
                    type: string
                    enum: [INBOUND, OUTBOUND]
                    description: '`OUTBOUND` for an SMS you sent, `INBOUND` for a reply to your Short Code.'
                    example: OUTBOUND
                sender:
                    type: string
                    description: Your Sender ID or Short Code, or the number a reply came from.
                    example: PonitorMFI
                recipient:
                    type: string
                    description: The phone number, in international format, or your Short Code for a reply.
                    example: '+231770000000'
                text:
                    type: string
                    description: The message.
                    example: Your Ponitor MFI code is 482910.
                status:
                    $ref: '#/components/schemas/MessageStatus'
                cost:
                    type: number
                    description: What the SMS cost, in US dollars. Refunded if it ends as `FAILED`.
                    example: 0.05
                failureReason:
                    type: string
                    nullable: true
                    description: Why it wasn't delivered, in plain words. Set for `EXPIRED`, `UNDELIVERED` and `FAILED`.
                    example: null
                failureCode:
                    $ref: '#/components/schemas/FailureCode'
                externalId:
                    type: string
                    nullable: true
                    description: Your `externalId`. `null` for a reply someone sent you.
                    example: otp-58213
                conversationId:
                    type: string
                    format: uuid
                    nullable: true
                    description: Groups the messages with one person, such as replies to your Short Code.
                    example: null
                createdAt:
                    type: string
                    format: date-time
                    description: When Ponitor accepted it.
                updatedAt:
                    type: string
                    format: date-time
                    description: When it last changed, usually its latest status.

        SmsMessageResponse:
            type: object
            required: [message]
            properties:
                message:
                    $ref: '#/components/schemas/SmsMessage'

        WhatsAppMessage:
            type: object
            description: |-
                A WhatsApp message you sent or received. The message is in the field named after
                its type: `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`,
                `contacts`, `order` or `template`. Only the ones it has are there.
            required: [id, channel, direction, sender, recipient, messageType, inServiceWindow, status, cost, failureReason, failureCode, externalId, conversationId, createdAt, updatedAt]
            properties:
                id:
                    type: string
                    format: uuid
                    example: 9b2e4c71-3a5d-4f8e-b1c6-7d0a2e9f4b13
                channel:
                    type: string
                    enum: [WHATSAPP]
                    example: WHATSAPP
                direction:
                    type: string
                    enum: [INBOUND, OUTBOUND]
                    description: '`OUTBOUND` for a message you sent, `INBOUND` for one a customer sent you.'
                    example: OUTBOUND
                sender:
                    type: string
                    description: Your WhatsApp number, or the customer's for a message they sent.
                    example: '+231770000000'
                recipient:
                    type: string
                    description: The customer's number, or yours for a message they sent.
                    example: '+231880000000'
                messageType:
                    type: string
                    nullable: true
                    enum: [TEMPLATE, FREE_FORM]
                    description: '`TEMPLATE` or `FREE_FORM` for a message you sent. `null` for one a customer sent.'
                    example: FREE_FORM
                inServiceWindow:
                    type: boolean
                    nullable: true
                    description: |-
                        `true` for a free-form message, which can only go inside the customer's
                        24-hour window. `null` for a template, and for a message a customer sent.
                    example: true
                text:
                    type: string
                    description: The message's text, or for a template what the customer read.
                    example: Thanks for your payment. Your receipt is on its way.
                image:
                    $ref: '#/components/schemas/ShapedFile'
                video:
                    $ref: '#/components/schemas/ShapedFile'
                audio:
                    $ref: '#/components/schemas/ShapedFile'
                document:
                    $ref: '#/components/schemas/ShapedFile'
                sticker:
                    $ref: '#/components/schemas/ShapedFile'
                location:
                    $ref: '#/components/schemas/Location'
                contacts:
                    type: array
                    items:
                        $ref: '#/components/schemas/ContactCard'
                order:
                    type: object
                    description: A customer's order from your WhatsApp catalog.
                template:
                    type: object
                    description: The template it was sent from. `text` holds what the customer read.
                    properties:
                        id:
                            type: string
                            format: uuid
                        name:
                            type: string
                        language:
                            type: string
                reply:
                    type: object
                    description: The button or quick reply a customer tapped, or the list row they picked.
                    properties:
                        id:
                            type: string
                        title:
                            type: string
                        description:
                            type: string
                buttons:
                    type: array
                    items:
                        $ref: '#/components/schemas/ReplyButton'
                list:
                    $ref: '#/components/schemas/ReplyList'
                link:
                    $ref: '#/components/schemas/LinkButton'
                referral:
                    type: object
                    description: The click-to-WhatsApp ad the customer wrote from.
                forwarded:
                    type: string
                    enum: [FORWARDED, FREQUENTLY_FORWARDED]
                status:
                    $ref: '#/components/schemas/MessageStatus'
                cost:
                    type: number
                    description: What the message cost, in US dollars. Refunded if it ends as `FAILED`.
                    example: 0.03
                failureReason:
                    type: string
                    nullable: true
                    description: Why it wasn't delivered, in plain words. Set for `EXPIRED`, `UNDELIVERED` and `FAILED`.
                    example: null
                failureCode:
                    $ref: '#/components/schemas/FailureCode'
                externalId:
                    type: string
                    nullable: true
                    description: Your `externalId`. `null` for a message a customer sent you.
                    example: reply-58213
                conversationId:
                    type: string
                    format: uuid
                    nullable: true
                    description: Groups the messages with one customer.
                    example: 0b1f6a52-5f3e-4f0e-9a43-2a7c4c1d2e3f
                smsFallback:
                    type: object
                    description: Only on a message you sent with an SMS fallback.
                    required: [sender, text, messageId]
                    properties:
                        sender:
                            type: string
                            example: PonitorMFI
                        text:
                            type: string
                        messageId:
                            type: string
                            format: uuid
                            nullable: true
                            description: |-
                                The SMS's id once it has gone, to read at `GET /sms/{id}`. `null` until
                                then.
                createdAt:
                    type: string
                    format: date-time
                    description: When Ponitor accepted it.
                updatedAt:
                    type: string
                    format: date-time
                    description: When it last changed, usually its latest status.

        WhatsAppMessageResponse:
            type: object
            required: [message]
            properties:
                message:
                    $ref: '#/components/schemas/WhatsAppMessage'

        MessageStatus:
            type: string
            description: |-
                `QUEUED` until the network accepts it, then `SENT`, then `DELIVERED`, `EXPIRED`,
                `UNDELIVERED` or `UNKNOWN`. `FAILED` means the network never accepted it, so it
                isn't charged. A message a customer sent you is `DELIVERED`.
            enum: [QUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN, FAILED]
            example: DELIVERED

        FailureCode:
            type: string
            nullable: true
            description: |-
                The same reason as a code from the error reference, such as `E11001`. Branch on
                this, not on `failureReason`.
            pattern: '^E11[0-9]{3}$'
            example: null

        EmailRequest:
            type: object
            additionalProperties: false
            required: [to, template, externalId]
            properties:
                to:
                    type: string
                    format: email
                    maxLength: 254
                    description: The one address to send to.
                    example: ada@example.com
                template:
                    type: string
                    maxLength: 64
                    description: |-
                        The handle of one of your templates, such as `verification-code`. Each
                        template's handle is under Email › Templates.
                    example: verification-code
                values:
                    type: object
                    description: |-
                        A value for each of the template's `{{variables}}`, by name. Every variable
                        the template uses needs one.
                    maxProperties: 100
                    additionalProperties:
                        type: string
                        maxLength: 1000
                    example:
                        code: '482913'
                from:
                    type: string
                    format: email
                    description: |-
                        The address of one of your senders. Its name goes with it. Leave it out to
                        send from your default sender.
                    example: billing@mail.example.com
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: |-
                        Your own reference for this email, unique within your team. Sending it again
                        returns the email it made the first time.
                    example: signup-8812

        EmailStatus:
            type: string
            enum: [QUEUED, SENT, DELIVERED, DELAYED, BOUNCED, COMPLAINED, FAILED]
            example: QUEUED

        Email:
            type: object
            required: [id, externalId, from, to, subject, templateName, status, cost, refunded, failureReason, createdAt, sentAt]
            properties:
                id:
                    type: string
                    format: uuid
                    example: 3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b
                externalId:
                    type: string
                    nullable: true
                    description: Your `externalId`. `null` for an email sent from the web app.
                    example: signup-8812
                from:
                    type: string
                    description: The sender's name and address, as inboxes show it.
                    example: '"Example" <hello@mail.example.com>'
                to:
                    type: string
                    example: ada@example.com
                subject:
                    type: string
                    description: The subject, with the values filled in.
                    example: Your code is 482913
                templateName:
                    type: string
                    nullable: true
                    description: The name of the template it was drawn from, as it was then.
                    example: Verification Code
                status:
                    $ref: '#/components/schemas/EmailStatus'
                cost:
                    type: number
                    format: double
                    description: What your account was charged, USD.
                    example: 0.002
                refunded:
                    type: boolean
                    description: Whether its cost went back to your account. Always `true` for a `FAILED` email.
                    example: false
                failureReason:
                    type: string
                    nullable: true
                    description: Why it failed, when its status is `FAILED`.
                    example: null
                createdAt:
                    type: string
                    format: date-time
                    description: When it was charged and queued.
                sentAt:
                    type: string
                    format: date-time
                    nullable: true
                    description: When it left for the inbox.

        EmailEvent:
            type: object
            required: [type, at, detail]
            properties:
                type:
                    type: string
                    description: |-
                        What happened. `OPENED` and `CLICKED` are kept for open and click tracking,
                        which isn't on yet.
                    enum: [QUEUED, SENT, DELIVERED, DELAYED, BOUNCED, COMPLAINED, OPENED, CLICKED, FAILED]
                    example: DELIVERED
                at:
                    type: string
                    format: date-time
                detail:
                    type: string
                    nullable: true
                    description: Why it bounced or failed, when it did.
                    example: null

        EmailResponse:
            type: object
            required: [email]
            properties:
                email:
                    $ref: '#/components/schemas/Email'

        EmailWithEventsResponse:
            type: object
            required: [email]
            properties:
                email:
                    allOf:
                        - $ref: '#/components/schemas/Email'
                        - type: object
                          required: [events]
                          properties:
                              events:
                                  type: array
                                  description: What happened to it, oldest first.
                                  items:
                                      $ref: '#/components/schemas/EmailEvent'

        HealthResponse:
            type: object
            properties:
                status:
                    type: string
                    example: 'ok'
                uptime:
                    type: number
                    example: 86400
                version:
                    type: string
                    example: '1.1.0'

        ErrorResponse:
            type: object
            description: >-
                Every error has `error`: its code, which never changes, and what it means
                (docs.ponitor.com/api/errors). `message`, `code` and `errors` beside it are
                deprecated: they're kept for integrations that read them, and will go.
            required: [error, message]
            properties:
                error:
                    type: object
                    required: [type, code, name, message, doc_url]
                    properties:
                        type:
                            type: string
                            description: The kind of error, for branching broadly.
                            enum: [internal_error, validation_error, bad_request_error, payload_too_large_error, not_found_error, conflict_error, unprocessable_error, rate_limit_error, service_unavailable_error, auth_error, permission_error, billing_error]
                            example: billing_error
                        code:
                            type: string
                            description: The error's code, E and five digits. Branch on this. It never changes.
                            pattern: '^E[0-9]{5}$'
                            example: E03001
                        name:
                            type: string
                            description: A readable name for the code.
                            example: InsufficientBalance
                        message:
                            type: string
                            description: What happened, to show or log. Don't parse it; it can change.
                            example: Insufficient account balance. Top up to continue sending.
                        doc_url:
                            type: string
                            format: uri
                            description: The code's entry in the error reference.
                            example: https://docs.ponitor.com/api/errors#E03001
                        request_id:
                            type: string
                            description: The request's id, also sent as the X-Request-Id header. Quote it to support.
                            example: 2d017493-d307-4628-b9a3-068160069183
                        param:
                            type: string
                            description: The one field at fault, when only one is.
                            example: externalId
                        details:
                            type: array
                            description: On a validation error (E01001), every field at fault.
                            items:
                                type: object
                                required: [param, message]
                                properties:
                                    param:
                                        type: string
                                        description: The field, as a dotted path.
                                        example: recipients.0
                                    message:
                                        type: string
                                        example: externalId is required
                message:
                    type: string
                    deprecated: true
                    description: The same as error.message.
                code:
                    type: string
                    deprecated: true
                    description: An older code a few errors had, such as RECIPIENT_OPTED_OUT. Use error.code.
                errors:
                    type: array
                    deprecated: true
                    description: On a validation error, each problem's message. Use error.details.
                    items:
                        type: object
                        properties:
                            message:
                                type: string

    examples:
        SmsQueued:
            summary: An SMS, charged and queued
            value:
                message:
                    id: 6c22adb9-8d60-45aa-a412-8d930cd6b334
                    channel: SMS
                    direction: OUTBOUND
                    sender: PonitorMFI
                    recipient: '+231770000000'
                    text: Your Ponitor MFI code is 482910.
                    status: QUEUED
                    cost: 0.05
                    failureReason: null
                    failureCode: null
                    externalId: otp-58213
                    conversationId: null
                    createdAt: '2026-11-07T09:00:00.112Z'
                    updatedAt: '2026-11-07T09:00:00.112Z'

        SmsDelivered:
            summary: Delivered
            value:
                message:
                    id: 6c22adb9-8d60-45aa-a412-8d930cd6b334
                    channel: SMS
                    direction: OUTBOUND
                    sender: PonitorMFI
                    recipient: '+231770000000'
                    text: Your Ponitor MFI code is 482910.
                    status: DELIVERED
                    cost: 0.05
                    failureReason: null
                    failureCode: null
                    externalId: otp-58213
                    conversationId: null
                    createdAt: '2026-11-07T09:00:00.112Z'
                    updatedAt: '2026-11-07T09:00:04.530Z'

        SmsUndelivered:
            summary: Not delivered
            value:
                message:
                    id: 2d7a91c4-6e3b-4f0a-9c58-b1e4d7f20a36
                    channel: SMS
                    direction: OUTBOUND
                    sender: PonitorMFI
                    recipient: '+231770000001'
                    text: Your Ponitor MFI code is 715304.
                    status: UNDELIVERED
                    cost: 0.05
                    failureReason: The number may no longer exist
                    failureCode: E11002
                    externalId: otp-58214
                    conversationId: null
                    createdAt: '2026-11-07T09:02:10.408Z'
                    updatedAt: '2026-11-07T09:02:15.861Z'

        WhatsAppText:
            summary: A reply in text, inside the 24-hour window
            value:
                message:
                    id: 9b2e4c71-3a5d-4f8e-b1c6-7d0a2e9f4b13
                    channel: WHATSAPP
                    direction: OUTBOUND
                    sender: '+231770000000'
                    recipient: '+231880000000'
                    messageType: FREE_FORM
                    inServiceWindow: true
                    text: Thanks for your payment. Your receipt is on its way.
                    status: QUEUED
                    cost: 0.03
                    failureReason: null
                    failureCode: null
                    externalId: reply-58213
                    conversationId: null
                    createdAt: '2026-11-07T10:15:00.204Z'
                    updatedAt: '2026-11-07T10:15:00.204Z'

        WhatsAppTemplate:
            summary: A template, with an SMS if they're not on WhatsApp
            value:
                message:
                    id: 8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d
                    channel: WHATSAPP
                    direction: OUTBOUND
                    sender: '+231770000000'
                    recipient: '+231880000000'
                    messageType: TEMPLATE
                    inServiceWindow: null
                    template:
                        id: 6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b
                        name: payment_reminder
                        language: en
                    text: Hi Konah, your loan payment of $25.00 is due on 14 November.
                    status: QUEUED
                    cost: 0.03
                    failureReason: null
                    failureCode: null
                    externalId: remind-0412
                    conversationId: null
                    smsFallback:
                        sender: PonitorMFI
                        text: Hi Konah, your loan payment of $25.00 is due on 14 November.
                        messageId: null
                    createdAt: '2026-11-07T09:30:00.112Z'
                    updatedAt: '2026-11-07T09:30:00.112Z'

        WhatsAppReceived:
            summary: A message a customer sent you
            value:
                message:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    channel: WHATSAPP
                    direction: INBOUND
                    sender: '+231880000000'
                    recipient: '+231770000000'
                    messageType: null
                    inServiceWindow: null
                    text: When is my next payment due?
                    status: DELIVERED
                    cost: 0.005
                    failureReason: null
                    failureCode: null
                    externalId: null
                    conversationId: 0b1f6a52-5f3e-4f0e-9a43-2a7c4c1d2e3f
                    createdAt: '2026-11-07T10:14:12.930Z'
                    updatedAt: '2026-11-07T10:14:12.930Z'

        EmailQueued:
            summary: An email, charged and queued
            value:
                email:
                    id: 3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b
                    externalId: signup-8812
                    from: '"Ponitor MFI" <hello@mail.example.com>'
                    to: ada@example.com
                    subject: Your code is 482913
                    templateName: Verification Code
                    status: QUEUED
                    cost: 0.002
                    refunded: false
                    failureReason: null
                    createdAt: '2026-11-07T12:00:00.000Z'
                    sentAt: null

        EmailDelivered:
            summary: Delivered, with what happened to it
            value:
                email:
                    id: 3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b
                    externalId: signup-8812
                    from: '"Ponitor MFI" <hello@mail.example.com>'
                    to: ada@example.com
                    subject: Your code is 482913
                    templateName: Verification Code
                    status: DELIVERED
                    cost: 0.002
                    refunded: false
                    failureReason: null
                    createdAt: '2026-11-07T12:00:00.000Z'
                    sentAt: '2026-11-07T12:00:05.000Z'
                    events:
                        - type: QUEUED
                          at: '2026-11-07T12:00:00.000Z'
                          detail: null
                        - type: SENT
                          at: '2026-11-07T12:00:05.000Z'
                          detail: null
                        - type: DELIVERED
                          at: '2026-11-07T12:00:09.000Z'
                          detail: null

    securitySchemes:
        oauth2:
            type: oauth2
            description: |-
                A bearer token from your team's OAuth client, with the client credentials grant.
                POST your client ID and secret (HTTP Basic) with `grant_type=client_credentials` to
                `/oauth2/token` on the same host you call: `https://sandbox-api.ponitor.com` for a
                sandbox client, `https://api.ponitor.com` for a live one. Send the token as
                `Authorization: Bearer <token>` until it expires (`expires_in`, in seconds), then
                get another.
            flows:
                clientCredentials:
                    tokenUrl: https://api.ponitor.com/oauth2/token
                    scopes: {}
        apiKeyAuth:
            type: apiKey
            in: header
            name: apiKey

    responses:
        400BadRequest:
            description: Bad request
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        401Unauthorized:
            description: Missing or invalid authentication credentials
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        403Forbidden:
            description: Access forbidden
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        404NotFound:
            description: Resource not found
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        409Conflict:
            description: The `externalId` is already on a message of the other channel
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        500ServerError:
            description: Internal server error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'

security:
    - oauth2: []
    - apiKeyAuth: []
