Validate messages without sending

Runs the same validation and pricing as Send messages but sends nothing. Use it to check sender IDs, recipients and message length, and to see how many parts and credits a send will use.

POST

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

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

Returns

200

Validation result. Valid messages have no ulid because nothing was sent.

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

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