URL | Verbs | Fields | Error Codes
Use this API to work with messages to members of a subscription list and other groups of subscribers.
https://app.mojotxt.com/api/v1/{phone_number}/messages/{verb}/{MessageID}
| 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. |
| Field | Type (Limit) | Required | Notes |
|---|---|---|---|
| MessageID | Integer | N/A | Read-Only - A unique identifier for this message. |
| UserID | Integer | N/A | Read-Only - The MojoTxt user who created this message. Null for messages added through the API. |
| ScheduleType | String (S or R) | No | 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 a 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 field is ignored when adding a message. |
| 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. Automations created in the app can also show minute or weekday here. |
| SendTime | String | N/A | Read-Only - For automations created in the app: the time of day to send, as HH:MM in your account's time zone. Otherwise null. |
| SendWeekday | Integer | N/A | Read-Only - For automations created in the app that send on a day of the week (SendAfterUnit is weekday): the day, from 0 to 6. Otherwise null. |
| Type | String (SMS or MMS) | No | The type of message to send ("SMS" or "MMS"). If omitted, the API chooses the type from the message: a message with Media is MMS, text that fits in two SMS segments is SMS, and longer text is sent as an MMS. |
| Message | String (1600) | Yes | The body of the message. An SMS is limited to two segments (306 characters, or 134 if the message contains emoji or special characters). An MMS is limited to 1,600 characters. If a link is attached, this is reduced by 19 characters to make room for the auto-generated short URL at the end of the message. |
| Attach | String (See Notes) | No | Attach a link to the end of each outbound message. Supported options are: link (the URL field), html (a web page made from the HTML field), profile (the subscriber's profile page), none. If URL is included and Attach is not, the API assumes link. |
| HTML | String | Yes, if Attach is html | The content of the web page when Attach is set to html. |
| URL | String (150) | Yes, if Attach is link | If included, a tokenized tracking URL will be generated and attached to the end of each outbound message. |
| Media | String (URL) | No | Use this field to specify a media attachment, as an http or https URL. JPG, GIF, or PNG files of 450 KB or less are supported. A larger file is refused with error 1411. Other attachment types are accepted with varying device compatibility. Media is ignored if Type is SMS. |
| 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 |
| StatusMessage | String | N/A | Read-Only - More detail about the sending status, if any. |
| Lists | Array(Integers) | See Notes | An array containing the List IDs of the Lists that this message was sent to. To add a message, Lists or another audience parameter is required. See Add A Message. |
| Filters | Array(Objects) | N/A | Returned by the get verb. The other groups this message was sent to, each with a FilterType and Criteria. |
| Recipients | Array(Integers) | N/A | Returned by the get verb. The subscriber ids of the specific people this message was sent to. |
| 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 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/+15555550100/messages/get/100) |
| 1401 | Messages | Message object does not exist. | The MessageID you specified doesn't exist, or belongs to a different phone number. |
| 1402 | Messages | No ListID, Recipients or audience specified. | An add request needs Lists or another audience parameter. A Relative (ScheduleType R) message needs Lists. |
| 1403 | Messages | Invalid ListID. | The list you specified does not exist within this phone number. On add requests, this code is returned for any list, fund, person or other audience ID that isn't on this phone number, with a message that says which. |
| 1404 | Messages | Empty Message. | The Message parameter was left empty (the message has no text). |
| 1405 | Messages | Message too long. | The message is longer than the limit for its Type. See the Message field above. |
| 1406 | Messages | Invalid Publish Time. | The PublishTime parameter could not be parsed to a date/time. This code is also returned when a Relative message has an invalid or missing SendAfter or SendAfterUnit. |
| 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, or is longer than 150 characters. This code is also returned for an invalid Attach value, or an empty HTML parameter when Attach is html. |
| 1409 | Messages | Cannot modify a sent message. | The specified message has already been sent, and it cannot be modified. |
| 1410 | Messages | Cannot delete a sent message. | The specified message has already been sent, and it cannot be deleted. |
| 1411 | Messages | Media URL invalid. | The Media parameter isn't a valid http or https URL, or the file is too large. |
| 1412 | Messages | Invalid Type. | If set, type must be either "SMS" or "MMS" (case sensitive). This code is also returned when the Type is "MMS" and this phone number can't send MMS. |
| 1413 | Messages | Your account is inactive. Reactivate it to send messages. | An inactive account can't add or update messages. It can still delete an unsent message. |
| 9999 | Messages | This appears to be a duplicate message. Another message with identical content was scheduled within the past 5 minutes. | The same message was added to this phone number within the last 5 minutes. A link at the end of the message doesn't make it different. |