Send your first MMS.

Before you send

You need an enabled MMS Express account, an available account balance, a server-side API key and permission to contact the recipient. Confirm your API origin and testing arrangements with us. This page does not assume a public sandbox or a charge-free send mode.

Set MMS_EXPRESS_BASE_URL to the approved HTTPS API origin, such as the origin provided during integration setup, without /api/v1. The website origin and API origin may differ. Use the correct credentials for the agreed environment.

Send Authorization: Bearer $MMS_EXPRESS_API_KEY. Keep the key in server environment variables or your secret store. Never embed it in browser JavaScript, a mobile client, a public repository or a URL.

Prefer an international recipient number in +27 format. South African local numbers beginning with 0 are normalised to +27; formatting validation does not establish ownership, current network, availability or compatibility. Use only authorised supported recipients. Read South African availability and receiver requirements and responsible-use information.

Start with a statement image

1. Export the relevant document content to a legible still image. Check the current limits below.
2. Persist a unique business request ID as MMS_EXPRESS_IDEMPOTENCY_KEY. Keep it with the exact request for recovery.
3. Submit to POST /api/v1/messages. Store the returned id.
4. Read GET /api/v1/messages/{id} or process verified webhook events. HTTP 202 means accepted for processing.

The JSON request below uses placeholders. Replace them with your authorised recipient and an immutable, approved image URL served over HTTPS. For private documents, prefer the multipart upload example so you do not need to publish a source URL.

POST /api/v1/messages
Authorization: Bearer $MMS_EXPRESS_API_KEY
Idempotency-Key: $MMS_EXPRESS_IDEMPOTENCY_KEY
Content-Type: application/json

{
  "to": "<authorised +27 recipient>",
  "text": "Your September statement is attached.",
  "media": [
    { "url": "https://example.invalid/statement.jpg" }
  ]
}

Download runnable server-side examples

The document and message are examples. Running an example against a live account submits a chargeable message; the website preview itself sends nothing.

Images, documents and actual limits

GET /api/v1/message-limits with messages:send returns the effective maximumTextCharacters, maximumMediaBytes and kilobyteBytes (1024). Fetch these when preparing a send. Server validation remains authoritative if settings change.

compressImages: true requires targetImageSizeKb from 1 to 10240. The target applies to each output image and does not override the total MMS limit. Supplying a target with compression disabled is rejected. If the target cannot be reached within the implemented readability safeguards, the request fails instead of silently shrinking the image dimensions.

joinImages: true requires at least two images and no other attachment types. It joins them vertically in request order, subject to the same processing and final-size checks. Without joining, each input still image becomes a separate JPEG. Check the final result in a controlled test before sending long or detailed statements.

Remote media must be reachable over HTTPS and pass network-address, type, size and redirect checks. Do not put credentials in URLs. A mutable URL can change its content before the first successful acceptance: use immutable content, or upload the exact bytes. An exact replay returns the retained message rather than fetching the URL again.

Submit a message

POST /api/v1/messages accepts JSON or multipart/form-data. Both require messages:send. One request names one recipient.

Send Idempotency-Key as an HTTP header, not a JSON field. It is optional in the API and strongly recommended for every integration. Use a non-blank value of at most 128 characters without control characters.

Acceptance, history and status

A successful submission returns 202 Accepted, a Location for message retrieval, and a JSON object. An exact idempotent replay also returns 202 and sets idempotentReplay to true; its status may have progressed since the original request.

The following is an illustrative projection of the response. Account-specific financial fields are omitted from this public example.

{
  "id": "msg_11111111111111111111111111111111",
  "status": "queued",
  "idempotentReplay": false,
  "conversationId": "conv_22222222222222222222222222222222",
  "nextEligibleAt": null,
  "queueReason": null,
  "finalMediaSizeBytes": 102400
}

GET /api/v1/messages/{id} with messages:read returns HTTP 200 for an accessible message, or 404 when it is not found in that account. Its JSON fields are:

• Identity and content: id, direction, from, to, nullable text, status, transport (mms or sms for recorded incoming messages).
• Context: nullable channelId, channelName, conversationId, inReplyToMessageId, and boolean replyLinkInferred. An inferred reply link is not proof of recipient intent.
• Timing and outcome: createdAt, nullable receivedAt, nextEligibleAt, queueReason, failureCode and failureMessage. Date-time values use ISO 8601 with an offset.
• Media: finalMediaSizeBytes and a media array with id, fileName, contentType, sizeBytes and downloadUrl. Read account media at GET /api/v1/media/{id} with the same read scope; URLs are not anonymous document links.
• History: an events array with timestamp, status and description. Financial fields priceCharged and currency are available only in the authenticated response.

GET /api/v1/messages supports optional search, direction, status, page (default 1) and pageSize (default 50, maximum 100). Its JSON envelope is { items, page, pageSize, total }. List items contain id, direction, counterparty, textPreview, status, channel, hasAttachments, timestamp, transport, conversationId, nextEligibleAt and queueReason.

There is no delivered or read state in this contract. A missing event, timeout or delayed status is not a successful delivery. See the reliability methodology for outcome and timing definitions.

Retry the request safely

Persist the idempotency key before submitting and use the same key for recovery from an uncertain HTTP outcome. Matching account, recipient, text, media order/content or URL, channel and processing options return the retained message with idempotentReplay: true. They do not submit a second message or debit again.

Reusing a key for a different request returns 409 idempotency_conflict. Do not “fix” that conflict by generating a new key until your application has reconciled the original business request. Keep immutable source images and the submitted manifest. Do not assume a documented expiry window or indefinite idempotency after historical records are removed; retain your own business-request record.

For a connection failure, timeout, 429 or retryable server failure, use bounded exponential backoff with jitter and the same request/key. A later 202 can be an exact replay. Once you have a message ID, retrieve its state instead of creating another send. A failed or uncertain sending outcome needs review; a client retry of the original request is not permission to resend a possibly sent message.

Errors and request limits

Application errors use error, message and traceId. Preserve the trace ID for support and handle the stable error code. Framework validation or an upstream HTTP service can return a different body; do not assume every failure is JSON.

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used for a different request, or retained historical evidence cannot prove an exact replay.",
  "traceId": "example-trace-id"
}

Each API key has its own configured request allowance. Your effective allowance is shown in API key settings; upstream controls may also apply. This is an HTTP request limit, not a sending-throughput promise. Status polling shares the allowance. A Retry-After header is not guaranteed by this contract; use conservative bounded backoff when absent.

Receive signed webhook events

Create an endpoint with POST /api/v1/webhooks and webhooks:manage. Its URL must be a public HTTPS endpoint under your control. Supported events are message.sent, message.failed and message.received; incoming events depend on the account's available receiving capability.

{
  "url": "https://example.invalid/webhooks/mms-express",
  "events": ["message.sent", "message.failed"]
}

Creation returns HTTP 201 with { endpoint, secret }. The endpoint contains id, url, events, enabled, consecutiveFailures and createdAt. Save the signing secret securely at creation; listing endpoints does not reveal it. It is a different credential from your API key.

Each POST to your receiver has X-MMS-Express-Event, X-MMS-Express-Timestamp (Unix seconds) and X-MMS-Express-Signature. Verify:

v1=lowercase_hex(
  HMAC_SHA256(signing_secret, timestamp + "." + exact_raw_JSON_body)
)

1. Read bounded raw request bytes before JSON middleware rewrites them. Reject missing, duplicated/ambiguous or malformed signature headers.
2. Reject timestamps outside your chosen tolerance; the downloadable receiver uses five minutes either side of its clock. Keep your clock synchronised. The timestamp is refreshed for each attempt, so retry age is not event age.
3. Compute HMAC-SHA256 over the timestamp, a full stop and the original UTF-8 body. Compare signatures in constant time.
4. Only then parse the event, and require the signed body's id to equal the event header.
5. Atomically store the event ID and enqueue its work in a durable inbox with a unique constraint. A previously committed identical event is a successful duplicate. Send a 2xx acknowledgement only after that commit; return an error if persistence fails.

The JSON envelope is { id, type, createdAt, data: { message } }. Its message contains id, direction, transport, from, to, text, status, channelId, conversationId, inReplyToMessageId, replyLinkInferred, finalMediaSizeBytes, receivedAt, failureCode, failureMessage and media with id, fileName, contentType and sizeBytes. Store payloads privately and avoid body logging.

Non-success responses and transport failures are retried using a bounded, configurable exponential schedule. Repeated failures can disable an endpoint. Attempts can duplicate and need not arrive in business-event order; use message retrieval to reconcile current state. A webhook's successful delivery means your HTTPS receiver acknowledged it, not that the customer received the MMS.

Download the server-side examples

These are plain-text source files. Rename them as described below, review them and set environment variables on your server. They do not run from this page and include no live credentials or preselected real recipient.

Set MMS_EXPRESS_BASE_URL, MMS_EXPRESS_API_KEY (send and read scopes), MMS_EXPRESS_TO, and a persisted MMS_EXPRESS_IDEMPOTENCY_KEY. For cURL, set MMS_EXPRESS_IMAGE_PATH; for the other send examples, set MMS_EXPRESS_MEDIA_URL. All examples submit once and retrieve the status once. Build durable request storage, bounded recovery and your business-specific error handling into your integration.