Skip to main content

SMS and MMS

The messaging endpoints use the same scheduled delivery queue and tenant SMS routing as the web interface. A concrete tenant code or name is required for every request, including requests authenticated with a global key. Full keys can send messages and download MMS attachment content. Full and read-only keys can retrieve stored message text and attachment metadata.

MethodEndpointPurpose
POST/smsQueue one outgoing SMS.
POST/mmsQueue one outgoing MMS with one attachment.
GET/smsList stored SMS history.
GET/mmsList stored MMS history.
GET/sms/{id}Retrieve one stored SMS.
GET/mms/{id}Retrieve one stored MMS and its attachment metadata.
GET/mms/{id}/attachments/{attachment_id}/downloadDownload an original stored attachment as binary data.

Sending

Send JSON with these fields:

  • to: required string containing one destination number, 2-79 digits with an optional leading +. Preserve leading zeroes by using a string.
  • from: optional sender number or alphanumeric ID; maximum 80 letters, digits, +, _, . or -. Default is empty; the existing tenant routing may select or rewrite the sender.
  • body: required nonempty UTF-8 text for SMS; optional for MMS. Tabs and newlines are allowed. The maximum is the lower of MAXSMSLENGTH (1024 when unset) and the database sm_body column capacity (normally 255 characters). Overlong messages are rejected without truncation.
  • not_before: optional future date/time in YYYY-MM-DD HH:MM:SS using PBX server time, years 1970-2037. Defaults to the current database time. Past times are rejected.
  • attachment: required for MMS only. An object containing filename and data_base64. Use a basename of 1-200 letters, digits, _, . or -, starting with a letter or digit. Supply canonical base64 encoding of a nonempty file, maximum 16 MiB. Provider limits may be lower. One outgoing attachment is supported, matching the existing sender. MMS to internal SIP/PJSIP extensions is rejected because their existing delivery path does not send media.

Unknown message or attachment fields are rejected. Sending requires InnoDB for the tenant, history, delivery queue and (for MMS) media tables. The history row, attachment and queue entry are committed together, or rolled back together if a write fails.

curl --request POST 'https://pbx.example.com/pbx/openapi.php/sms?tenant=TENANT' \
  --header 'X-API-Key: YOUR_FULL_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"to":"+390212345678","from":"+390298765432","body":"Hello from MirtaPBX"}'

For MMS, encode the local file, then submit the JSON using jq. This example uses uuencode -m for base64 encoding:

jq -n \
  --arg to '+390212345678' \
  --arg from '+390298765432' \
  --arg data "$(uuencode -m /tmp/photo.jpg photo.jpg | sed '1d;$d' | tr -d '\n')" \
  '{to:$to,from:$from,body:"Photo attached",attachment:{filename:"photo.jpg",data_base64:$data}}' \
  | curl --request POST 'https://pbx.example.com/pbx/openapi.php/mms?tenant=TENANT' \
      --header 'X-API-Key: YOUR_FULL_API_KEY' \
      --header 'Content-Type: application/json' \
      --data-binary @-

A successful send returns HTTP 202 Accepted:

{"id":123,"queue_id":456,"type":"sms","tenant_id":15,"status":"queued","to":"+390212345678","from":"+390298765432","not_before":"2026-10-25 14:30:00"}

HTTP 202 confirms queuing, not delivery. croncheck.php dispatches the message using the existing tenant SMS routing and DEFAULTSMSSERVER setting; external MMS requires an MMS-capable provider. The returned id identifies the SCHEDULED history row. The existing sender writes separate delivery history and does not update that row. queue_id identifies the pending delivery entry, which is consumed by the existing dispatcher. Repeating a successful POST creates another message.

Retrieving history

Both lists return newest IDs first and accept:

  • limit: 1-500, default 100.
  • before_id: return older IDs; use next_before_id from the preceding page.
  • direction: IN or OUT.
  • from, to, status: exact-match filters. Status is the stored value, such as SCHEDULED, RECEIVED or DELIVERED.
  • start, end: inclusive PBX server date/time bounds, in YYYY-MM-DD HH:MM:SS format.
curl --get 'https://pbx.example.com/pbx/openapi.php/sms' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'tenant=TENANT' \
  --data-urlencode 'direction=IN' \
  --data-urlencode 'start=2026-10-25 00:00:00' \
  --data-urlencode 'end=2026-10-25 23:59:59' \
  --data-urlencode 'limit=100'

The response is {"data":[...],"limit":100,"has_more":false,"next_before_id":null}. No total COUNT query is performed. Each message contains id, tenant_id, type, datetime, direction, from, to, body, status, real_source, from_type, to_type and unread. Detail responses also contain an attachments array with id, filename and bytes for each stored attachment.

Example History Response

{
  "data": [
    {
      "id": 123,
      "tenant_id": 15,
      "type": "sms",
      "datetime": "2026-10-25 14:30:00",
      "direction": "IN",
      "from": "+390212345678",
      "to": "+390298765432",
      "body": "Message received",
      "status": "RECEIVED",
      "real_source": "",
      "from_type": "SMS",
      "to_type": "SMS",
      "unread": true
    }
  ],
  "limit": 100,
  "has_more": false,
  "next_before_id": null
}

SMS/MMS classification follows the stored sm_mms=yes flag. Only retained history/media can be retrieved; if message storage was disabled for an incoming message, its body is not recoverable through the API. Reading does not mark a message as read. Raw provider responses and media access keys are omitted.

curl 'https://pbx.example.com/pbx/openapi.php/mms/123?tenant=TENANT' \
  --header 'X-API-Key: YOUR_API_KEY'

curl 'https://pbx.example.com/pbx/openapi.php/mms/123/attachments/789/download?tenant=TENANT' \
  --header 'X-API-Key: YOUR_FULL_API_KEY' \
  --output /tmp/received-photo.jpg

The download returns application/octet-stream with an attachment filename and the original bytes. Unknown messages, mismatched types, foreign-tenant messages and unavailable attachments return HTTP 404. Read-only sending/downloading returns 403; invalid payloads/filters return 400; unsupported methods return 405; incompatible configuration returns 409. Errors use the standard JSON error structure. A rejected write includes rollback information when a transaction was started.

Query-style routing is also supported: ?object=sms&action=send&tenant=TENANT with POST, ?object=sms&action=list&tenant=TENANT, ?object=mms&action=get&id=123&tenant=TENANT, and ?object=mms&action=download&id=123&attachment_id=789&tenant=TENANT with GET.