# 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>]`&#x20;

**Examples**

* `http://example.com/inbound_messages`
* `http://username:password@example.com:8080/inbound_messages`
* `https://johndoe:secret@example.com:8080/messages/mms/tsg_inbound`

MM4 Routing Address

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

**Examples**

* `mm4://example.com:2526`
* `mm4://johndoe:secret@example.com: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:

```http
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": [
            "+13462239287/TYPE=PLMN@mmsc.tsgglobal.world"
          ]
        },
        "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"
    }
  ]
}
```


---

# 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/receive-an-mms-message.md?ask=<question>
```

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.