MM7 Gateway

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 with an API key
A US/Canada long code, toll-free number, or short code with MMS enabled, assigned to a messaging profile
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.

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

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:

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:

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"
  }
}

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.

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

Send MMS via the JSON Messages API with media attachments.

Messaging Profiles

Configure profiles, webhooks, and number pools.

Receiving Webhooks

Standard JSON webhook setup and signature verification.

MMS Media & Transcoding

Supported media formats and carrier size limits.

Sending Messages

Messaging Profiles

Short Code

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

For AI Agents

Prerequisites

Send MMS via MM7

Request

Response

Status codes

Limits

Receive MMS via MM7

Troubleshooting

Next steps

Send & Receive MMS

Messaging Profiles

Receiving Webhooks

MMS Media & Transcoding

​Prerequisites

​Send MMS via MM7

​Request

​Response

​Status codes

​Limits

​Receive MMS via MM7

​Troubleshooting

​Next steps

Send & Receive MMS

Messaging Profiles

Receiving Webhooks

MMS Media & Transcoding

Prerequisites

Send MMS via MM7

Request

Response

Status codes

Limits

Receive MMS via MM7

Troubleshooting

Next steps