URL | Verbs | Fields | Error Codes

Use this API to work with messages to members of a subscription list.

URL Scheme{phone_number}/messages/{verb}/{MessageID}

Available Verbs

Verb Description
list Retrieve a list of messages.
get Get a specific message by its ID.
add Schedule a new message for sending.
update Update an unsent message.
delete Delete an unsent message.

Message Object Fields

Field Type (Limit) Required Notes
MessageID Integer N/A Read-Only - A unique identifier for this message.
ScheduleType String (S or R)   If set to S (Specific), the message will be scheduled at a specific date and time. If set to R (Relative), the message will be sent at a time relative to when a person subscribes to this list.
PublishTime UNIX Timestamp (Integer) No

If ScheduleType is set to S (Specific), this is the time the message should be sent, expressed in UNIX timestamp format. If not provided, the message will be sent immediately. If provided, it must be a time in the future.

If ScheduleType is set to R (Relative), this is the earliest time the message could possibly be sent.

SendAfter Integer Yes, if ScheduleType is R The amount of time to wait between when a person subscribes and the message is sent.
SendAfterUnit String (See Notes) Yes, if ScheduleType is R The unit of time that SendAfter is expressed in. Supported options are: hour, day, week, month, year.
Type String (SMS or MMS) No The type of message to send ("SMS" or "MMS"). If omitted, the API will assume SMS.
Message String (138-1600) Yes The body of the message. This field is limited to 160 characters for SMS or 1,600 for MMS. If a URL is included, this is reduced by 22 characters to make room for the auto-generated short URL at the end of the message.
Media String (300) Yes, if MMS When sending an MMS message, use this field to specify the media attachment. JPG, GIF, or PNG files less than 5 MB are supported. Other attachment types are accepted with varying device compatibility.
URL String (150) No If included, a tokenized tracking URL will be generated and attached to the end of each outbound message.
Sent Integer N/A Read-Only - The sending status of the message.
0 = Scheduled for Delivery / In Delivery Queue
1 = Sent
2 = Sending
3 = Failure
Lists Array(Integers) Yes An array containing the List IDs of the Lists that this message was sent to. (Send in the querystring form: Lists[]=1&Lists[]=2 to specify an array of more than one list.)
MessagesSent Integer N/A Read-Only - The number of recipients to whom this message was sent.
LinksClicked Integer N/A Read-Only - The number of recipients who clicked the link associated with this message (if applicable).

Error Codes

Error Code Endpoint Description Notes
1000-1099 API Core (Multiple) See API Error Codes
1400 Messages No Message object specified. A MessageID is required for this request (i.e. /api/v1/+12225551212/messages/get/100?ListID=10)
1401 Messages Message object does not exist. The MessageID you specified doesn’t exist, or belongs to a different list.
1402 Messages No ListID specified. A ListID parameter is required for add requests.
1403 Messages Invalid ListID. The list you specified does not exist within this phone number.
1404 Messages Empty Message. The Message parameter was left empty (the message has no text).
1405 Messages Message too long. The message was longer than 160 characters (or 138 characters with a link).
1406 Messages Invalid Publish Time. The PublishTime parameter could not be parsed to a date/time.
1407 Messages Publish Time in the past. The PublishTime parameter was set to a date or time in the past.
1408 Messages Invalid link URL. The URL parameter does not contain a valid URL.
1409 Messages Cannot modify a sent message. The specified message has already been sent, or is in the process of sending, and it cannot be modified.
1410 Messages Cannot delete a sent message. The specified message has already been sent, or is in the process of sending, and it cannot be deleted.
1411 Messages Media URL invalid or missing. If the message Type is "MMS", a valid "Media" URL is required.
1412 Messages Invalid Type. If set, type must be either "SMS" or "MMS" (case sensitive).