Send an MMS Message
Easily send an MMS message with some media content.
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer <api_key>"
post
https://mmsc.tsgglobal.world/mms
Send an MMS message.
{
"data": {
"id": "1354f59f-7cfc-46de-981a-f750d443f9ec",
"type": "mms-forward-req",
"attributes": {
"from": "+12342341234",
"to": ["+12003004000"],
"subject": "This is a test",
"transaction_id": "c52e6196-4ef6-4ce4-8c89-a0a12791c298",
"request_delivery_reports": true,
"headers": {
"cc": ["[email protected]"],
"to": ["[email protected]", "[email protected]"]
},
"parts": [
{
"kind": "plain",
"headers": {},
"content_type": "text/plain",
"content_location": "my_text.txt",
"content_encoding": "identity",
"transfer_encoding": "identity",
"body": "Hello, World",
"uri": null,
"metadata": {}
},
{
"body": null,
"content_encoding": "identity",
"content_location": null,
"content_type": "image/png",
"decoded": false,
"headers": {},
"kind": "uri",
"metadata": {},
"transfer_encoding": "identity",
"uri": "http://example.com/image.png"
}
]
}
}
}
Delivery Receipts (DLRs)
DLRs for MMS messages are customer-enabled by optionally flagging a request for a DLR when POSTing to the API. Please include “request_delivery_reports”: true as in the above example, requesting that a DLR be sent to you. Omitting or setting it to false will result in no DLRs being forwarded to you.
Part Kinds
plain
{
"kind": "plain",
"body": "Hello, World"
}
Plain parts are used for text attachments, these include
text/*
media types that do not include any binary or restricted characters (i.e. nulls).data-uri
{
"kind": "data-uri",
"content_location": "MyText.txt",
"uri": "data:text/plain;name=<MyText.txt>,Hello%20World"
}
RFC2397 data URIs may be used to specify content_encoding, content_type and body in a single string. These strings however have a 65535 character limit.
uri
{
"kind": "uri",
"content_type": "item.png",
"uri": "http://example.org/item.png"
}
Parts can also be provided as URIs, the content_type will be taken from the request or determined based on the extension of the link.
Content downloaded from a URI must be 3 MB or less, otherwise it will be rejected and the message will have a nulled attachment.
The requested resource MUST return a valid
Content-Length
, failure to do so will result in the attachment being nullified. NOTE: The server MUST respond to HEAD and GET requests for the attachment to be retrieved.embedded
{
"kind": "embedded",
"content_type": "image/png",
"transfer_encoding": "base64",
"body": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QwLFhYQGrly9gAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAAApUlEQVQ4y2P8//8/Q1N6wH8GMkDdzA2MjI1p/v+l5MQYRMQESNL85tUHhmePXjEwMTAwkKwZWQ8TqRovnbmFwmeiRDNJBsA065mokW4ATLOUnBiGHAu5NmO44NKZWxh+xGczhgEwGy6ducXw5tUHFMPwRTNKGMBsevboFYYYUQaIiAlgaCCUyJiwpTCYIbgCjmAsiIgJEJ28mWAZg1QA08NIaXYGABYVP8mp45LoAAAAAElFTkSuQmCC"
}
Parts MAY be embedded, in which all the data is included but MAY be compressed or encoded in a different format for transfer. Data in an embedded body must NOT exceed 1Mb (when compressed)
The body of the part will be decoded by applying:
transfer_encoding
content_encoding
To encode the part, apply the encodings in the reverse.
Note: All headers are subject to filter and may be excluded.
Any headers that start with following will not be added to the message:
x-mms-
content-
checksum-
x-checksum-
message-id
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Cowboy
Date: Wed, 23 Oct 2019 18:50:03 GMT
X-Request-ID: FdBbQM5NGxGrvxkAAAUG
{
"data": {
"id": "4e36a1f7-fd9c-4851-8087-918902fc204e",
"type": "mms-forward-res",
"attributes": {
"inserted_at": "2019-10-24T00:48:53.312285Z",
"transaction_id": "e7184cf1-1837-4318-a2cd-82c847830541",
"from": "12003004005",
"to": ["13746648333"],
"subject": "Hello",
"headers": {},
"parts": [
{
"id": "text-part@localhost",
"content_type": "text/plain",
"content_length": "11",
"content_encoding": "identity",
"transfer_encoding": "identity",
"kind": "plain"
}
]
}
}
}
# Single character
\n - Line-feed / New-line
\r - Carriage-return
\s - Whitespace (spaces are printable however)
\t - Horizontal-tab
# Unicode
\uXXXX - Unicode character, here X is a hexadecimal value
// Incorrect
{
"body": "These
are
new
lines
that
aren't
escaped
"
}
// Correct
{
"body": "These\nare\nnew\nlines\nthat\nare\nescaped"
}
{
"body": "Have a smile 😁"
}
{
"body": "Have a smile \uD83D\uDE00",
}
Q - What is the maximum plain body text limit for an MMS message
A - We recommend using 1000 characters or less.
Q - How many participants can I have in an MMS conversation
A - We recommend having 10 or fewer participants in an MMS conversation.
Q - My request failed with a 400 Bad Request and a message saying unexpected character at X
A - The JSON payload was malformed, did you include any new lines inside strings?
Q - How can I send a Line-feed/Carriage-return/other-non-printable-characters?
A - JSON supports several escape sequences for handling non-printable-characters (see above).
Q - Can I send UTF-8 characters?
A - Yes you can, the API supports UTF-8 encoding.
Q - Can I send an emoji?
A - Yes you can, either using the unicode escape sequence or the UTF-8 character.
Last modified 15d ago