Receive an MMS Message

Overview

Get your message returned via SMTP or via a webhook URL that you provide.

Routing Address

When requesting routing for your MMS messages, you may either specify an MM4 (SMTP) or HTTP endpoint.

It’s possible to provide Basic authentication details with the routing address:

HTTP Routing Address

(http|https)://[<username>:<password>@]<hostname>[:<port>][/*<path>]

Examples

• http://example.com/inbound_messages

• http://username:[e-mail]:8080/inbound_messages

• https://johndoe:[e-mail]:8080/messages/mms/tsg_inbound

MM4 Routing Address

mm4://[<username>:<password>@]<hostname>[:<port>]

Examples

• mm4://example.com:2526

• mm4://johndoe:[e-mail]:2526

Webhook Format

All requests are made using the POST HTTP Verb to the specified endpoint.

Similar to the HTTP API, the webhook uses the very same format for delivering messages.

The request will include the following headers:

Accept: application/json
Content-Type: application/json
User-Agent: Marshmallow/prod-x.y.z
X-Session-ID: aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa

NOTE: additional headers may be included that are not listed here.

Webhook Response

When responding to the webhook request, respond with a 2xx status, more specifically:

• 200 OK

• 202 Accepted

• 204 No Content

Any of these statuses will be accepted as an acknowledgement of receive.

Otherwise the MMS system will assume delivery failed and will retry an additional 2 times within it’s current timeframe. If this fails once more, the message will be placed unto the retry and tried at a later time. The message will be retried a total of 20 times with an exponential backoff.

Once a message is received by the system and it’s routing is determined, it cannot be re-routed.

Note: All messages will keep their routing, changing a did’s routing will NOT affect messages already in-flight, this ensures that a message meant for an old endpoint will be delivered to that endpoint and nowhere else.

Example Response

{
  "data": [
    {
      "attributes": {
        "expires_at": null,
        "from": "14252437709",
        "headers": {
          "to": [
            "[phone]/TYPE=[e-mail]"
          ]
        },
        "inserted_at": "2022-04-06T21:50:06.316116",
        "metadata": {},
        "parts": [
          {
            "body": null,
            "content_encoding": "identity",
            "content_length": null,
            "content_location": "476CC8E7CD30DBE0..unk",
            "content_type": "application/smil",
            "decoded": false,
            "headers": {},
            "id": "7a1ebff0-a8b7-4a24-b951-85b04ac6855a",
            "kind": "uri",
            "metadata": {},
            "transfer_encoding": "identity",
            "uri": "https://content.mms.smshub.world/prod/7160ce4c-0205-4e47-9eb7-3954991911c2/parts/476CC8E7CD30DBE0..unk"
          },
          {
            "body": null,
            "content_encoding": "identity",
            "content_length": null,
            "content_location": "image0000.JPG",
            "content_type": "image/jpeg",
            "decoded": false,
            "headers": {},
            "id": "7c2459ec-95b9-454d-8d9a-0293442b6459",
            "kind": "uri",
            "metadata": {},
            "transfer_encoding": "identity",
            "uri": "https://content.mms.smshub.world/prod/7160ce4c-0205-4e47-9eb7-3954991911c2/parts/photo.JPG"
          }
        ],
        "pool_name": null,
        "request_delivery_reports": false,
        "subject": "",
        "to": [
          "13462239287"
        ],
        "transaction_id": "74def178-695b-4f04-9acd-efb3b0e7dab9",
        "version": "2020-01-14"
      },
      "id": "61d55de8-8ccd-4bf3-8b51-848a8c21919b",
      "type": "mms-forward-req"
    }
  ]
}