# Send an MMS Message ## Overview Easily send an MMS message with some media content. ## Authentication {% hint style="info" %} Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \" (using the messaging API key specifically). API credentials can be found here: {% endhint %} ## Method ## Send an MMS message. `POST` `https://mmsc.tsgglobal.world/mms` The MMS API attempts to mirror an MM4 request, as such it shares some structural similarities and naming. Particularly the use of the ‘type’ field to denote the type of request. Currently only Forward Requests are available. #### Request Body | Name | Type | Description | | --------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | An id, this id may be used to track the message. Note: this can be considered a reference\_id. | | type\* | string | What type of data should we expect with this message. Should always be `"mms-forward-req"`Note: failure to provide this value will cause the request to fail immediately. | | expires\_at | datetime | An ISO8601 formatted timestamp, this designates when the message should expire within the system, expired messages will be dropped if they expire before leaving the queues. | | expires\_in | integer | A duration in seconds after the message has been received to expire, this will be added to the time of receiving the message to create an `expires_at` value. | | transaction\_id | string | This field will be used as the transaction-id of the message, if none is provided, one will be generated. | | from\* | string | The originator number, should be formatted as E164. | | to\* | list\ | A list of recipients, each number should be formatted as E164. | | subject | string | An optional subject header to apply to the message. | | headers | map | An optional map of additional headers to include in the message. | | metadata | map | Any additional data to include in the payload, will be returned on response. | | parts\* | list | A list of parts that make up the body of the message. | | kind | string | What kind of content does the part contain?, default “plain”. | | headers | map\ | Any additional headers to include in the part. | | content\_type | string | What is the media type of the part?, if none is given this will default to text/plain, unless the kind is a uri or data-uri. | | content\_location | string | The name of the attachment, in case a custom SMIL is provided, this will allow referencing the part. | | content\_encoding | string | Any special encodings applied to the body of the part, usually a compression method. | | transfer\_encoding | string | Any special encodings applied to the body of the part, normally for transport over HTTP/S. | | body\* | string | The body or content of the part, may or not be encoded as required. | | uri | string | A URI that is publically accessible that can be downloaded to get the content of the MMS. Content exceeding 3mb will be rejected. | | request\_delivery\_reports | boolean | Requesting DLR for the message to be sent to you. Defaults to false | {% tabs %} {% tab title="200: OK Upon successfully sending an MMS request you will receive a response. This does not mean that the MMS has been sent or delivered, only that it has been accepted by the system for further processing." %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## Example POST ``` { "data": { "type": "mms-forward-req", "attributes": { "from": "+12223334444", "to": [ "+14252437709" ], "headers": {}, "metadata": {}, "parts": [ { "headers": {}, "metadata": {}, "content_location": "body.txt", "kind": "plain", "content_type": "text/plain", "body": "This is a test MMS for the body" }, { "headers": {}, "metadata": {}, "content_location": "aurora.jpg", "kind": "uri", "uri": "https://s3.amazonaws.com/content.mms.smshub.world/sample/sample-768x1024.jpg" } ] } } } ``` ```json { "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": ["+12003005000@example.com"], "to": ["+12003004000@example.com", "+12003004001@example.com"] }, "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` ```json { "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` ```json { "kind": "data-uri", "content_location": "MyText.txt", "uri": "data:text/plain;name=,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` ```json { "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. {% hint style="warning" %} 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. {% endhint %} * `embedded` ```json { "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` ## Example 200 OK Response ``` 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": {}, "messages": [{ "message_id": "9f3a72e9-7dc2-4741-96c7-ff2049b49b11", "to": "13746648333" }], "parts": [ { "id": "text-part@localhost", "content_type": "text/plain", "content_length": "11", "content_encoding": "identity", "transfer_encoding": "identity", "kind": "plain" } ] } } } ``` `data.attributes.messages` will contain a message for each recipient. The provided `message_id` will be used to reference the message in DLRs. ## Additional Examples ### Example - Escape Special Characters ``` # 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 ``` ### Example - New Lines in Body ```javascript // Incorrect { "body": "These are new lines that aren't escaped " } // Correct { "body": "These\nare\nnew\nlines\nthat\nare\nescaped" } ``` ### Example - the UTF-8 character - for more information please refer to RFC8259 ```javascript { "body": "Have a smile 😁" } ``` ### Example - JSON Unicode escape ```javascript { "body": "Have a smile \uD83D\uDE00", } ``` ## Frequently Asked Questions 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tsgglobal.com/api-reference/programmable-mms/send-an-mms-message.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.