Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Send MMS

This endpoint allows you to send an MMS, or multimedia message to a recipient. MMS messages extend SMS messages by allowing various multimedia components like images, short video clips and audio recordings. Similar to an SMS message, a MMS message needs the following paramaters for it to be delivered to a recipient.

  • It must be from a valid phone number on your account.
  • It must be sent to a valid recipient’s phone number.
  • It must contain at a minimum, a short message.
  • It can optionally have one or more multimedia components. If no multimedia is specified, the message will be sent as a regular SMS instead.

How We Determine the From Number on an Outgoing MMS

  1. If you specify a user_id or pin value of a user on your account, we will attempt to use that user’s associated phone number if they have communication abilities enabled. This essentially means we’re sending a SMS out on behalf of this user.
  2. If you specify the from_number directly, we will attempt to use that as long as it matches a valid and active line on your account.
  3. If no from_number is specified, or no user_id/pin is specified, or the specified user has no number AND no caller id, we will attempt to use the account-wide text from number setting.
  4. If we cannot determine a from number, we return an error response to you.

How we Associate an Outgoing Text With a User

Texts sent using this endpoint can be associated with a user on your account. This means that we record the user’s id value with the call data record so that the text shows up in the user’s individual history, and in your reports. In order to associate the text with a user, you must specify the user_id or pin value below.

Content Type Required

You MUST use a Content-Type of multipart/form-data in your POST request to us when using this endpoint. Essentially, you are making a HTTP POST request to our servers using a MIME encoded multipart request body. Here is a stackovorflow discussion if you’re interested in the details.

API Request

URL Parameters
Standard Request Parameters
Parameter Type Usage Description
to_number string Required A phone number in 10 digit or E.164 format
payload string Required The text message to send.
account_id integer Depends Specify the account id explicitly to send the text using this account. Optional for users. Required for integrators.
user_id integer Optional Associate the message with this user and attempt to use the user’s number as the text from number.
pin integer Optional Alternatively, specify the user with the PIN instead of user_id.
from_number string Optional Specify the form number directly. This must be an active line on your account.
extra object Optional A JSON string containing any key:value pairs that you want to get sent back to you via the Push or RealTime API. See notes for extra data.
Multimedia Request Parameters

Here is how you include multimedia contents with your message. The following shows a hypothetical scenario where two images were included with a MMS message. The parameter name is free form. We used “image1” and “image2”, but you could use your own names here. The content type of each sub-part of your POST should be specified so we know what kind of content is being sent to us (image, video, etc). It sounds compliated, but it’s well supported by most HTTP client libraries.

Parameter Type Content-Type Description
image1 binary image/jpeg The image data will be encoded and passed to us. We send it along to the recipient.
image2 binary image/jpeg The second image data will be encoded in this sub-part. We send this along too.
Response Body
   "success": true,
   "guid": "e3038b20-e487-497d-ab1e-361f4f8590a9",
      "sendType": "immediate",
      "uniqueId": "T.150472313191523499155290",
      "reason": "Nominal operation"
Error Code Description
OPT_OUT The recipient/to number is on the opt-out list
INVALID_ACCOUNT The account id, if specified, is not valid or you do not have access to it.
INVALID_CAMPAIGN The from number does not match an active, valid Line/Campaign on your account.
INVALID_FROM_NUMBER The from number is malformed or invalid.
INVALID_TO_NUMBER The recipient/to number is malformed or invalid.
INVALID_USER The specified user does not exist on the account.