Add A Message

Add (send) a new message.

https://app.mojotxt.com/api/v1/{phone_number}/messages/add

Use the Type parameter to specify whether you are sending an SMS or MMS message. 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. If this phone number can't send MMS, longer text returns error 1405.

The Message parameter is required, along with Lists or another parameter from the audience table below. You can also specify the PublishTime (UNIX timestamp when the message will be sent) and the URL (to include a link). See the Message Object fields for every option. You can send parameters as part of the GET querystring, or as POST data. Fields not included with your request will be ignored.

Upon success, the server will return the newly created object's MessageID in the "created_id" response field.

Who Gets The Message:

A person who matches any of these parameters receives the message, unless they have opted out. Tags then narrows that group. A Relative (ScheduleType R) message uses only Lists.

Parameter	Options	Description
Lists	Array of ListIDs	Everyone subscribed to these lists.
Recipients	Array of subscriber ids	These specific people (up to 10,000). Each must already be on this phone number.
Everyone	1	Everyone on this phone number.
AnyList	1	Everyone subscribed to any list on this phone number.
AnyFund	1	Everyone who has donated to any fund on this phone number.
Funds	Array of DonationIDs	Everyone who has donated to these funds.
Responders	Array of IDs	Everyone who has used these auto-responders.
Polls	Array of IDs	Everyone who has voted in these polls.
Programs	Array of IDs	Everyone subscribed to these daily programs.
Tags	Array of tag IDs	Keep only the people above who also have one of these tags. Tags alone doesn't choose anyone.
Filters	Array of objects, each with FilterType and Criteria	Another way to send the choices above. FilterType is one of l (any list), t (narrow by tag), d (narrow by fund), everyone, tag, fund, responder, poll, or program. Criteria is the ID, where the FilterType needs one.

Sending an array: use Lists[]=173 and Lists[]=174. In a GET querystring, Lists=173&Lists=174 and Lists=173,174 work too.

Example SMS Request:

GET https://app.mojotxt.com/api/v1/+15555550100/messages/add?Type=SMS&Message=Test+Message&Lists=173&Lists=174&PublishTime=1893456000&URL=https%3A%2F%2Fexample.com

-or-

POST https://app.mojotxt.com/api/v1/+15555550100/messages/add
DATA Type=SMS                          /* Sending an SMS */
     Message=Test Message              /* The message text to send. */
     Lists[]=173                       /* The list to send to. */
     Lists[]=174                       /* A second list to send to. */
     ScheduleType=S                    /* Send at a specific date and time */
     PublishTime=1893456000            /* The time the message should be sent. */
     URL=https%3A%2F%2Fexample.com     /* A link to add to the end of the message (URL Encoded). */

Example Result:

{
    "result": "success",
    "timestamp": 1793491200,
    "request": {
        "Type": "SMS",
        "Message": "Test Message",
        "Lists": [
            "173",
            "174"
        ],
        "PublishTime": "1893456000",
        "URL": "https://example.com",
        "object": "messages",
        "verb": "add",
        "phone": "+15555550100"
    },
    "message": "The message was added successfully.",
    "created_id": 708
}

Example MMS Request:

GET https://app.mojotxt.com/api/v1/+15555550100/messages/add?Type=MMS&Message=Test+Message&Media=https%3A%2F%2Fexample.com%2Fimage.png&Lists=173&Lists=174&PublishTime=1893456000

-or-

POST https://app.mojotxt.com/api/v1/+15555550100/messages/add
DATA Type=MMS                                       /* Sending an MMS */
     Message=Test Message                           /* The message text to send. */
     Media=https%3A%2F%2Fexample.com%2Fimage.png    /* URL of image attachment. */
     Lists[]=173                                    /* The list to send to. */
     Lists[]=174                                    /* A second list to send to. */
     PublishTime=1893456000                         /* The time the message should be sent. */

Example Result:

{
    "result": "success",
    "timestamp": 1793491200,
    "request": {
        "Type": "MMS",
        "Message": "Test Message",
        "Media": "https://example.com/image.png",
        "Lists": [
            "173",
            "174"
        ],
        "PublishTime": "1893456000",
        "object": "messages",
        "verb": "add",
        "phone": "+15555550100"
    },
    "message": "The message was added successfully.",
    "created_id": 709
}