Vonage Sms API

openapi: 3.2.0
info:
  title: Vonage Sms API
  version: 1.5.1
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.vonage.com/
  x-metaDescription: Get started with the Vonage SMS API, a powerful tool for automating text message communications. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage SMS API Reference | Vonage API Documentation
  description: 'Operations tagged Sms across 2 of this provider''s published API definitions: vonage-sms-openapi.json, vonage-sms-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest.nexmo.com
security:
- basicAuth: []
tags:
- name: SMS
paths:
  /sms/{format}:
    post:
      operationId: send-an-sms
      summary: Send an SMS
      description: Send an outbound SMS from your Vonage account
      parameters:
      - name: format
        description: The format of the response
        in: path
        required: true
        schema:
          example: json
          type: string
          enum:
          - json
          - xml
          default: json
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NewMessage'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SMS'
                - $ref: '#/components/schemas/Error'
            text/xml:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SMSXml'
                - $ref: '#/components/schemas/ErrorXml'
      callbacks:
        delivery-receipt:
          '{$request.body#/callback}':
            post:
              summary: Delivery Receipt
              operationId: delivery-receipt
              description: The following are parameters sent in as a [delivery receipt](/messaging/sms/guides/delivery-receipts) callback. You can subscribe to [webhooks](/getting-started/concepts/webhooks) to receive notification when the delivery status of an SMS that you have sent with Vonage changes.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/DeliveryReceipt'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
      tags:
      - SMS
    servers:
    - url: https://rest.nexmo.com
components:
  schemas:
    SMS:
      description: Message sent
      type: object
      properties:
        message-count:
          type: string
          description: The amount of messages in the request
          example: '1'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    SMSXml:
      type: object
      description: Message sent
      xml:
        name: mt-submission-response
      properties:
        messages:
          x-skip-response-description: true
          type: array
          items:
            $ref: '#/components/schemas/Message'
          properties:
            count:
              type: integer
              example: 1
              xml:
                attribute: true
    ErrorXml:
      type: object
      description: Error
      xml:
        name: mt-submission-response
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'
    DeliveryReceipt:
      type: object
      properties:
        msisdn:
          type: string
          description: The number the message was sent to. Numbers are specified in E.164 format.
          example: '447700900000'
        to:
          type: string
          description: The SenderID you set in `from` in your request.
          example: AcmeInc
        network-code:
          type: string
          description: The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.
          example: '12345'
        messageId:
          type: string
          description: The Vonage ID for this message.
          example: 0A0000001234567B
        price:
          type: string
          description: The cost of the message
          example: '0.03330000'
        status:
          type: string
          description: A code that explains where the message is in the delivery process.
          example: delivered
          x-possible-values:
          - delivered
          - expired
          - failed
          - rejected
          - accepted
          - buffered
          - unknown
        scts:
          type: string
          description: When the DLR was received from the carrier in the following format `YYMMDDHHMM`. For example, `2001011400` is at `2020-01-01 14:00`
          example: '2001011400'
        err-code:
          type: string
          description: The status of the request. Will be a non `0` value if there has been an error, or if the status is unknown. See the [Delivery Receipt documentation](/messaging/sms/guides/delivery-receipts#dlr-error-codes) for more details
          example: '0'
        api-key:
          type: string
          description: The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.
          example: abcd1234
        message-timestamp:
          description: The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
          type: string
          example: '2020-01-01 12:00:00'
        client-ref:
          description: If a `client-ref` was included when sending the SMS, this field will be included and hold the value that was sent.
          type: string
          example: my-personal-reference
    ErrorMessage:
      type: object
      xml:
        name: message
      properties:
        status:
          type: string
          description: The error status of the message
          example: '2'
        error-text:
          type: string
          description: The description of the error
          example: Missing to param
    NewMessage:
      required:
      - from
      - to
      - text
      properties:
        api_key:
          description: Your API key. Only required if setting `sig`.
          type: string
          minLength: 8
          maxLength: 8
          example: abcd1234
        sig:
          description: 'The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.

            Note: **DO NOT** set an `Authorization` header when using `sig`.

            '
          type: string
          minLength: 16
          maxLength: 60
          example: 5d41402abc4b2a76b9719d911017c592
        timestamp:
          description: An integer containing the number of seconds since the epoch (this is sometimes also known as UNIX time). Only required if setting `sig`. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.
          type: integer
          example: 1617187200
        from:
          description: The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see [Global Messaging](https://developer.vonage.com/messaging/sms/guides/global-messaging#country-specific-features) for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.
          type: string
          example: AcmeInc
        to:
          description: The number that the message should be sent to. Numbers are specified in E.164 format.
          type: string
          minLength: 7
          maxLength: 15
          pattern: \d{7,15}
          example: '447700900000'
        text:
          description: The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the `type` to `text`. If your message contains characters outside this range, then you will need to set the `type` to `unicode`.
          type: string
          example: Hello World!
        ttl:
          description: '**Advanced**: The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.'
          type: integer
          example: 900000
          default: 259200000
          minimum: 20000
          maximum: 604800000
        status-report-req:
          description: '**Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).'
          type: boolean
          example: false
          default: true
        callback:
          description: '**Advanced**: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. Max 100 characters.'
          type: string
          example: https://example.com/sms-dlr
        message-class:
          description: '**Advanced**: The Data Coding Scheme value of the message'
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
        type:
          description: '**Advanced**: The format of the message body'
          type: string
          enum:
          - text
          - binary
          - unicode
          example: text
          default: text
        body:
          description: '**Advanced**: Hex encoded binary data. Depends on `type` parameter having the value `binary`.'
          type: string
          example: '0011223344556677'
        udh:
          description: '**Advanced**: Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on `type` parameter having the value `binary`.'
          type: string
          example: 06050415811581
        protocol-id:
          description: '**Advanced**: The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use. Ensure that the value is aligned with `udh`.'
          type: integer
          example: 127
        client-ref:
          description: '**Advanced**: You can optionally include your own reference of up to 100 characters.'
          type: string
          example: my-personal-reference
        account-ref:
          description: '**Advanced**: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})'
          type: string
          example: customer1234
        entity-id:
          description: '**Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)'
          type: string
          example: '1101456324675322134'
        content-id:
          description: '**Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)'
          type: string
          example: '1107457532145798767'
        trusted-number:
          description: 'Setting this parameter to `true` overrides, on a per-message basis, any protections set up via [Fraud Defender](https://developer.vonage.com/en/fraud-defender/overview) (Traffic Rules, SMS Burst Protection, AIT Protection).


            This parameter only has any effect for accounts subscribed to Fraud Defender Premium.

            '
          type: boolean
          example: true
          default: false
        pool-id:
          description: "The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the `from` number. \nThe `from` parameter is still required even when specifying a `pool-id` and will be used as a fall-back if the number pool cannot be used.\nSee the [Number Pools documentation](https://developer.vonage.com/numbers/number-pools-api/overview) for more information.\n"
          type: string
          example: abc123
    Message:
      type: object
      properties:
        to:
          type: string
          description: The number the message was sent to. Numbers are specified in E.164 format.
          example: '447700900000'
        message-id:
          type: string
          description: The ID of the message
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          xml:
            name: messageId
        status:
          type: string
          description: The status of the message. See [Troubleshooting Failed SMS](/messaging/sms/guides/troubleshooting-sms).
          example: '0'
        remaining-balance:
          type: string
          description: Your estimated remaining balance
          example: '3.14159265'
          xml:
            name: remainingBalance
        message-price:
          type: string
          description: The estimated cost of the message
          example: '0.03330000'
          xml:
            name: messagePrice
        network:
          type: string
          description: The estimated ID of the network of the recipient
          example: '12345'
        client-ref:
          description: If a `client-ref` was included when sending the SMS, this field will be included and hold the value that was sent.
          type: string
          example: my-personal-reference
        account-ref:
          type: string
          description: '**Advanced**: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})'
          example: customer1234
    Error:
      description: Error
      type: object
      properties:
        message-count:
          type: string
          description: The amount of messages in the request
          example: '1'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- vonage-sms-openapi.json
- vonage-sms-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one