Send an MMS

Use this endpoint to send an MMS from a Flowroute long code or toll-free phone number to another valid phone number. All Flowroute phone numbers are MMS-enabled. To get started, visit the DIDs page to view all of your Flowroute numbers.

MMS Limitations

You will need a Flowroute long code or toll-free phone number in order to send and receive messages.
Flowroute's maximum MMS message size is 750kB including text. You may have more than one media file attachment so long as they meet the total size limitation of 750kB.
You are allowed to send one MMS per API request, at a rate of 1 MMS per second.
Flowroute cannot guarantee delivery to any phone number not enabled for MMS.
Smart quotes are known to cause errors. Please make sure to use neutral (vertical) quotes in your request.

Endpoint

POST /messages

Body Parameters

to
string required
Valid phone number that you're sending the message to. This number must be in E.164 format. e.g. 12065551234
from
string required
Flowroute phone number that you're sending the message from. This must be a number that you own in your Flowroute account in E.164 format. e.g. 12065551234
body
string
Optional, if media_urls is specified.

The plain-text content of the message that is counted in the total message size which is currently restricted to 750kB. Depending on the length of your message and if you set it to MMS, your message may be broken into multiple fragments and sent as SMS instead. Refer to Message Length & Concatenation for specific information on MMS limitations.
media_urls
array of strings
Optional, if body is specified. The publicly accessible URL of the media that you are sending. You may attach more than one media file so long as they meet the size limitation of 750kB including text.
is_mms
boolean
A flag that you can set for sending a text-only MMS without specifying a media_urls.
dlr_callback
string
A callback URL that you can configure on a per message basis for delivery receipt updates. Upon sending your MMS, Flowroute will post the delivery receipts to the dlr_callback that you've set. To learn more, see Receive a DLR.

Note: this will override the global mms_dlr_callback if set (see the Set a Callback URL for an Account section for more information.).

Response Format

On success, the HTTP status code in the response header is 202 Accepted and the response body contains the message record ID with mdr2 prefix. On error, the header status code is an error code and the response body contains an array of error objects.

Response Fields

Upon successful configuration, Flowroute will start posting your inbound MMS messages to your MMS Callback URL. The HTTP status code in the response header is 200 OK and the response body contains a detailed message object in JSON format. If you don't receive the POST notifications, check that your callback service and MMS Callback URL are set up correctly.

data
object
Message object composed of the following:

price_details object - The pricing details of the message sent.

base_rate decimal - The base cost per message segment. Unit is USD.
charged_cost decimal - The total cost of the message. This is calculate by the following formula: (base_rate + surcharge_rate) * segment_count
segment_count int - The SMS industry standard for a single message is 160 characcters as defined in the GSM 03.38 standard
surcharge_rate decimal - The surcharge price per segment that the message incurred.

id
string
ID of the MMS message with the mdr2 prefix.
type
string
This will always be message.

Example Request

Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

POST /v2.2/messages HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "message",
    "attributes": {
      "to": "+12061231234",
      "from": "+18441231234",
      "body": "hey",
      "is_mms": "true",
      "media_urls": [
        "https://sbc.example.com/invoice.png", "http://s3.amazonaws.com/barkpost-assets/50+GIFs/37.gif"
      ]
    }
  }
}

Example Request

Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

POST /v2.2/messages HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "message",
    "attributes": {
      "to": "+12061231234",
      "from": "+18441231234",
      "body": "hey",
      "is_mms": "true",
      "media_urls": [
        "https://sbc.example.com/invoice.png", "http://s3.amazonaws.com/barkpost-assets/50+GIFs/37.gif"
      ]
    }
  }
}

Example Request

Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

curl https://api.flowroute.com/v2.2/messages -X POST \
-u accessKey:secretKey -H 'Content-Type: application/vnd.api+json' -d \
'{"data": {"type": "message", "attributes": {"to": "+120612131234", "from": "+18441231234", "body":"hey", "is_mms": "true", "media_urls":["https://sbc.example.com/invoice.png", "http://s3.amazonaws.com/barkpost-assets/50+GIFs/37.gif"]}}}'

Example Compact Request

This assumes that you have the Python API Wrapper installed and set up. Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.


# Instantiate the API client and create a controller for Messages
client = FlowroutenumbersandmessagingClient(basic_auth_user_name, basic_auth_password)
messages_controller = client.messages

# Create your test MMS
request_body = '{ \
      "data": { \
        "type": "message", \
        "attributes": { \
          "to": "YOUR_MOBILE_NUMBER", \
          "from": "YOUR_FLOWROUTE_NUMBER", \
          "body": "hey", \
          "is_mms": "true", \
          "media_urls": ["http://s3.amazonaws.com/barkpost-assets/50+GIFs/37.gif"] \
        } \
      } \
    }'

print ("---Send A Message")
result = messages_controller.send_a_message(request_body)
pprint.pprint(result)

Example Responses

202 ACCEPTED

"data": {
    "id": "mdr2-abc123",
    "links": {
      "self": "https://api.flowroute.com/v2.2/messages/mdr2-abc123"
    },
    "price_details": {
        "base_rate": 0.001,
        "charged_cost": 0.001,
        "segment_count": 1,
        "surcharge": 0.0000
      },
    "type": "message"
  }
}

415 Unsupported Media

{
        "errors": [
          {
            "detail": "Client Error: Must set Content-Type header to `application/vnd.api+json`",
            "id": "b843c607-cded-49b8-8884-4722210da2fd",
            "status": 415,
            "title": "Unsupported Media Type"
          }
        ]
      }

401 Unauthorized

{
  "errors": [
    {
      "detail": "Authentication failed.",
      "id": "7fc8c70a-ca58-430c-b383-b89df84f8083",
      "status": 401,
      "title": "Unauthorized"
    }
  ]
}

mms v2.2

About

Endpoints

ACCOUNT LEVEL MESSAGING CALLBACK SERVICES

PHONE NUMBER MESSAGING CALLBACK SERVICES

Related Articles

Send an MMS

MMS Limitations

Endpoint

Body Parameters

to

from

body

media_urls

is_mms

dlr_callback

Response Format

Response Fields

data

id

type

Example Request

Example Request

Example Request

Example Compact Request

Example Responses

202 ACCEPTED

415 Unsupported Media

401 Unauthorized