Customer.io
v1.0.0
OpenAPI 3.1.0

Send a transactional SMS

US region

Client Libraries
Shell Curl

Send a transactional SMS

​

Send a transactional SMS message. To send a message, you'll need to provide a transactional_message_id. This is either the numerical ID of your transactional message template or the Trigger Name that you assigned the template.

You can find your transactional_message_id from the code sample in the Overview tab for your transactional message in the user interface, or you can look up a list of your transactional messages through the App API.

Body
application/json
    • identifiers
      required

      Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.

      Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.

      • id
        Type: string
        required

        The identifier for the person represented by the transactional message. NOTE: If your workspace identifies people by email, use the email identifier instead.

    • to
      Type: string
      required

      The phone number you want to send your SMS to. Use E.164 format, like +15551234567, or Liquid if you store phone numbers as attributes.

    • transactional_message_id
      required

      The transactional message template that you want to use for your message. You can call the template by its numerical ID or by the Trigger Name that you assigned to the template in the UI (case insensitive).

      • Type: integer · ID (integer)

        The ID of the transactional message you want to send.

    • auto_create
      Type: boolean

      If true and your transactional_message_id doesn't match a record, Customer.io creates an empty record using that value as the Trigger Name. The ID must be a string. If the name already belongs to another channel, the request fails with 400, and numeric IDs ignore this setting. See details.

    • disable_message_retention
      Type: boolean

      If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.

    • from
      Type: string

      The phone number or sender ID your SMS is from. It must be verified in your Twilio account. This overrides the template's sender. Use E.164 format for a phone number.

    • language
      Type: string

      Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.

    • message_data
      Type: object

      An object containing the key-value pairs referenced using liquid in your message.

    • queue_draft
      Type: boolean

      If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.

    • send_at
      Type: integer

      A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.

    • send_to_unsubscribed
      Type: boolean

      If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.

    • tracked
      Type: boolean

      Whether to track link clicks for this SMS. Defaults to the transactional message's own tracking setting.

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/v1/send/sms
curl https://api.customer.io/v1/send/sms \
  --request POST \
  --header 'X-Workspace-Id: 100' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "transactional_message_id": "confirmation code",
  "to": "+15559876543",
  "from": "+15551234567",
  "identifiers": {
    "id": "123456"
  },
  "message_data": {
    "confirmation_code": "123456",
    "account_name": "Jane Doe"
  }
}'

{
  "delivery_id": "string",
  "queued_at": 1,
  "send_at": 1
}

Returns a unique ID for the delivery.