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.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /sms | Queue one outgoing SMS. |
| POST | /mms | Queue one outgoing MMS with one attachment. |
| GET | /sms | List stored SMS history. |
| GET | /mms | List 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}/download | Download 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 ofMAXSMSLENGTH(1024 when unset) and the databasesm_bodycolumn capacity (normally 255 characters). Overlong messages are rejected without truncation.not_before: optional future date/time inYYYY-MM-DD HH:MM:SSusing PBX server time, years 1970-2037. Defaults to the current database time. Past times are rejected.attachment: required for MMS only. An object containingfilenameanddata_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; usenext_before_idfrom the preceding page.direction:INorOUT.from,to,status: exact-match filters. Status is the stored value, such asSCHEDULED,RECEIVEDorDELIVERED.start,end: inclusive PBX server date/time bounds, inYYYY-MM-DD HH:MM:SSformat.
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.
No comments to display
No comments to display