Send messages

Send one or more SMS or MMS messages in a single request. Each message is validated on its own: valid messages are sent, and any that fail are returned in data.errors with an error_code and a human-readable error_help that you should log.

Requests must be sent as application/json. To send an MMS, include a single image URL in media and send from an MMS-enabled dedicated number.

POST

https://app.touchsms.com.au/api/v2/sms

Authorization

basicAuth
HTTP
required

Request body JSON required

messages
array of
object
required
Messages to send. MMS messages also go in this array.
- to
  string
  required
  Recipient number, ideally in E.164 format (+61412345678). Local formats are parsed but not recommended.
- from
  string
  required
  Sender ID: a dedicated number, verified phone number or verified alphanumeric sender ID on your account. Use E.164 for numbers, or SHARED_NUMBER to send from the shared pool.
- body
  optional
  string
  Message text. Unicode is accepted. Required unless media is given.
  
  maxLength: 1600
- campaign
  optional
  string
  Campaign name shown in reports. Defaults to API Campaign (<date>).
  
  maxLength: 190
- reference
  optional
  string
  Your reference, included in reports and delivery receipts.
  
  maxLength: 190
- metadata
  optional
  map of
  one of
  Up to 10 key/value pairs. Keys are strings of up to 50 characters; values are strings or integers of up to 100 characters.
- media
  optional
  array of
  string
  Send as MMS. One publicly accessible image URL (JPEG, PNG or GIF, up to 1MB). MMS must be sent from an MMS-enabled dedicated number and is not supported in every country. Set the MMS subject with the mms_subject metadata key (up to 40 characters).
  
  format: uri
- date
  optional
  string
  Schedule the message for this time (ISO 8601, UTC), for example 2024-03-11T22:52:07Z.
  
  format: date-time
}
opt_out_list_id
optional
integer
Reject recipients found in this opt-out list with RECIPIENT_OPTED_OUT. Cannot be combined with opt_out_list_name.
opt_out_list_name
optional
string
Name of an existing opt-out list to check recipients against. Cannot be combined with opt_out_list_id.

maxLength: 255
reject_duplicates
optional
boolean
Drop messages in this request with the same from, to and body as an earlier one.

default: false
reject_duplicates_by_recipient
optional
boolean
Send only the first message to each recipient in this request.

default: false

Example requests

{
  "messages": [
    {
      "to": "+61412345678",
      "from": "SHARED_NUMBER",
      "body": "Hi Sam, your order has shipped.",
      "reference": "order-1042",
      "metadata": {
        "order_id": 1042
      }
    }
  ]
}

{
  "messages": [
    {
      "to": "+61412345678",
      "from": "+61491570159",
      "body": "Here is your voucher",
      "metadata": {
        "mms_subject": "Your voucher"
      },
      "media": [
        "https://example.com/voucher.jpg"
      ]
    }
  ]
}

{
  "opt_out_list_name": "Marketing Opt-Outs",
  "reject_duplicates_by_recipient": true,
  "messages": [
    {
      "to": "+61412345678",
      "from": "SHARED_NUMBER",
      "body": "Spring sale starts today."
    }
  ]
}

Returns

200

Messages processed. Check data.errors for any messages that were rejected.

JSON

data
optional
object
- meta
  optional
  object
  Totals for the accepted messages.
  
  totalParts
  optional
  integer
  Total SMS parts across all accepted messages.
  
  totalMessages
  optional
  integer
  totalCredits
  optional
  number
  Total cost of the accepted messages.
  
  scheduledMessages
  optional
  integer
  Number of accepted messages that are scheduled.
  
  creditBalance
  optional
  number
  Your current credit balance. Dry run only.
  
  hasSufficientCredits
  optional
  boolean
  Whether your balance covers totalCredits. Dry run only.
- messages
  optional
  array of
  object
  Messages that were accepted.
  
  status
  optional
  VALID
  ulid
  optional
  string
  Unique message ID, also sent in delivery receipts. Not present on dry runs.
  
  to
  optional
  string
  from
  optional
  string
  body
  optional
  string | null
  campaign
  optional
  string | null
  campaign_id
  optional
  integer
  Present when the message was linked to an existing campaign.
  
  reference
  optional
  string | null
  metadata
  optional
  object | null
  date
  optional
  string | null
  Scheduled send time, or null to send now.
  
  format: date-time
  meta
  optional
  object
  size
  optional
  integer
  Message length in characters.
  
  parts
  optional
  integer
  Number of SMS parts.
  
  is_unicode
  optional
  boolean
  is_mms
  optional
  boolean
  cost
  optional
  number
  country
  optional
  string
  ISO country code of the recipient.
- errors
  optional
  array of
  object
  Messages that were rejected.
  
  status
  optional
  ERROR
  error_code
  optional
  INVALID_BODY
  or
  MESSAGE_TOO_LONG
  or
  INVALID_MEDIA
  or
  INVALID_METADATA
  or
  INVALID_RECIPIENT
  or
  INVALID_SCHEDULE
  +4 more
  
  INVALID_BODY: body is missing or invalid.
  
  MESSAGE_TOO_LONG: body is too long.
  
  INVALID_MEDIA: MMS media failed validation.
  
  INVALID_METADATA: metadata failed validation.
  
  INVALID_RECIPIENT: recipient is invalid or could not be parsed, or MMS is not supported to it.
  
  INVALID_SCHEDULE: date is invalid.
  
  INVALID_SENDER_ID: sender ID is invalid.
  
  UNAPPROVED_SENDER_ID: sender ID is not approved on your account.
  
  RECIPIENT_OPTED_OUT: recipient has opted out.
  
  DUPLICATE_MESSAGE: rejected by duplicate prevention.
  
  error_help
  optional
  string
  Human-readable explanation. Log this.
  
  to
  optional
  string
  from
  optional
  string
  body
  optional
  string
  campaign
  optional
  string
  reference
  optional
  string
  metadata
  optional
  object
  media
  optional
  array of
  string
  date
  optional
  string
  format: date-time
}

401

Missing, malformed or invalid API credentials.

JSON

message
string
required

406

Your account does not have enough credits for the send. No messages are sent. Scheduled sends are not checked.

JSON

message
optional
string
required
optional
number
Amount the send needs.
balance
optional
number
Your current balance.
is_postpaid
optional
boolean

422

The request failed validation. errors lists the messages for each invalid field.

JSON

message
optional
string
errors
optional
map of
array<string>

429

Rate limit exceeded. Wait before retrying.

JSON

message
string
required