> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MM7 Gateway

> Send and receive MMS over the MM7 protocol (SOAP/XML) using Telnyx's MM7 gateway, with profile-based webhook configuration for inbound MM7 messages and delivery reports.

MM7 is the 3GPP SOAP/XML protocol (TS 23.140) used by carrier MMSCs and enterprise MMS platforms. Telnyx exposes an MM7 gateway so systems that already speak MM7 can send and receive MMS through Telnyx without rewriting to the JSON Messages API. The gateway implements MM7 version **6.8.0**.

## Prerequisites

* A [Telnyx account](https://telnyx.com/sign-up) with an [API key](https://portal.telnyx.com/#/app/api-keys)
* A US/Canada long code, toll-free number, or short code with MMS enabled, assigned to a [messaging profile](https://developers.telnyx.com/docs/messaging/messages/messaging-profiles-overview.md)
* For receiving: a publicly reachable webhook endpoint that accepts `multipart/related` and `text/xml` POST requests

## Send MMS via MM7

Submit a standard MM7 `SubmitReq` to:

```
https://api.telnyx.com/v2/messaging/mm7/submit
```

Authenticate with your Telnyx API key as a Bearer token, exactly as for all other v2 API endpoints. The request is a `multipart/related` body: the first part is the MM7 SOAP envelope (`SubmitReq`), remaining parts are the media attachments.

The sender number must be owned by the account authenticating with the Bearer token. Each `SubmitReq` carries a `TransactionID` — Telnyx returns the same value in the response header so requests can be correlated.

> [!NOTE]
>
> The outbound MMS submitted via MM7 flows through the same routing, anti-spam, and rate-limiting pipeline as MMS sent through the Messages API. `SubmitReq` supports `To` and `Cc` recipients, `ShortCode` and `Number` address forms, and a `Subject` element. Media content is re-hosted on Telnyx storage.

### Request

```curl theme={null}
POST /v2/messaging/mm7/submit HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/related; boundary="MM7BOUNDARY"; type="text/xml"; start="<mm7_content>"

--MM7BOUNDARY
Content-Id: <mm7_content>
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <TransactionID>trans-001</TransactionID>
  </soapenv:Header>
  <soapenv:Body>
    <SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <SenderIdentification>
        <SenderAddress>
          <Number>+13115550000</Number>
        </SenderAddress>
      </SenderIdentification>
      <Recipients>
        <To>
          <Number>+13125550123</Number>
        </To>
      </Recipients>
      <Subject>Monthly invoice</Subject>
    </SubmitReq>
  </soapenv:Body>
</soapenv:Envelope>
--MM7BOUNDARY
Content-Type: image/jpeg
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD...
--MM7BOUNDARY--
```

Use `<ShortCode>` in place of `<Number>` for short-code senders and recipients.

### Response

On acceptance, Telnyx returns an MM7 `SubmitRsp` with status `1000` (Success) and the Telnyx `MessageID`:

```curl theme={null}
HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <TransactionID xmlns="...REL-6-MM7-1-4">trans-001</TransactionID>
  </soapenv:Header>
  <soapenv:Body>
    <SubmitRsp xmlns="...REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <Status>
        <StatusCode>1000</StatusCode>
        <StatusText>Success</StatusText>
      </Status>
      <MessageID>6b2f...-a1b2-c3d4</MessageID>
    </SubmitRsp>
  </soapenv:Body>
</soapenv:Envelope>
```

Delivery reports for MM7-submitted messages are delivered to your messaging profile's standard webhook as regular Telnyx JSON delivery events, unless you opt into MM7-native webhooks (see below).

## Status codes

The gateway always returns an MM7 response. Check both the HTTP status code and the `Content-Type` header: requests stopped at the edge router (authentication, routing) return a JSON error body instead of an MM7 response.

| StatusCode | StatusText | Meaning |
| - | - | - |
| `1000` | Success | Message accepted; `MessageID` is populated |
| `2000` | (varies) | Upstream request rejected (4xx from the messaging pipeline) |
| `2002` | (varies) | Missing or unknown `from` number, or missing recipient |
| `2007` | Parse Error | Malformed multipart, XML, or content type |
| `2560` | Body too large | Payload exceeded 2 MB |
| `2568` | (varies) | Send forbidden (e.g., account-level restriction) |
| `3510` | (varies) | Rate limited (HTTP 429 upstream) |
| `4006` | Service unavailable | Temporary upstream failure; retry |

## Limits

| Limit | Value |
| - | - |
| Payload size | 2 MB total request body (SOAP envelope + all media parts) |
| MM7 version | 6.8.0 (3GPP REL-6) |
| Recipients | `To` + `Cc` supported |
| Text | Truncated at 100 KB |

## Receive MMS via MM7

By default, inbound MMS and delivery reports arrive as regular Telnyx JSON webhooks. To receive them as MM7 payloads instead, configure `mm7_metadata` on the messaging profile that owns the destination numbers:

```curl theme={null}
PATCH /v2/messaging_profiles/{messaging_profile_id} HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "mm7_metadata": {
    "mm7_webhook_url": "https://example.com/mm7",
    "mm7_failover_webhook_url": "https://example.com/mm7-failover"
  }
}
```

> [!NOTE]
>
> If you have no failover webhook, omit `mm7_failover_webhook_url` from the request body. Passing an explicit `null` for either field is rejected with error `10026` (invalid parameter type).

With `mm7_metadata` configured, the profile's MM7 webhook receives POST requests with two payload types:

* **`DeliverReq`** — inbound MMS from a handset. The SOAP envelope names sender, recipients, and subject; the `multipart/related` body carries the message content parts, with `start` pointing at the SMIL part.
* **`DeliveryReportReq`** — MM7 delivery reports for messages submitted via MM7. The envelope carries the original `MessageID`, `MMStatus`, `StatusText`, sender, and recipient.

The webhook must accept POST requests from Telnyx IP addresses. A non-2xx response (or connection failure) to the primary webhook triggers delivery to `mm7_failover_webhook_url` when configured.

> [!WARNING]
>
> MM7 webhook payloads are not currently signed. Allowlist Telnyx IP addresses on your endpoint while payload signing is being added.

## Troubleshooting

> **Unknown 'from' number (2002)**
>
> The `SenderAddress` in the `SubmitReq` does not match a number owned by the authenticating account, the number is not assigned to a messaging profile, or an explicit `null` was sent for an `mm7_metadata` field. Verify number ownership and profile assignment.

> **Response is JSON, not MM7 XML**
>
> The request was stopped at the edge router before reaching the MM7 gateway — usually authentication or a malformed `Content-Type`. Confirm the Bearer token and that `Content-Type` is `multipart/related` with a `boundary` (and `start` pointing at the SOAP part). Check the HTTP status code alongside the body.

> **Body too large (2560)**
>
> The total request body — SOAP envelope plus all media parts, after any base64 expansion — must be under 2 MB. Split large media across multiple submissions or downscale media.

> **Not receiving MM7 webhooks**
>
> Confirm `mm7_metadata` is set on the messaging profile that owns the **destination** number for inbound, or the profile used at submit time for delivery reports. Without `mm7_metadata`, all events arrive as standard JSON webhooks. Also confirm the endpoint accepts `multipart/related` and `text/xml` POSTs and allowlists Telnyx IPs.

***

## Next steps

> **[Send & Receive MMS](https://developers.telnyx.com/docs/messaging/messages/send-receive-mms.md)**
>
> Send MMS via the JSON Messages API with media attachments.

> **[Messaging Profiles](https://developers.telnyx.com/docs/messaging/messages/messaging-profiles-overview.md)**
>
> Configure profiles, webhooks, and number pools.

> **[Receiving Webhooks](https://developers.telnyx.com/docs/messaging/messages/receiving-webhooks.md)**
>
> Standard JSON webhook setup and signature verification.

> **[MMS Media & Transcoding](https://developers.telnyx.com/docs/messaging/messages/mms-transcoding.md)**
>
> Supported media formats and carrier size limits.