Messages

Send a text or attachment to a recipient

View as Markdown
Routes an outbound iMessage to a single recipient phone number via a registered agent. Supports text, media attachments, and optional idempotency keys.

Authentication

X-App-Idstring

Your MessageBlue App ID, sent in clear on every request. It is paired with request signing: each request is also signed with your App Secret (see the Authentication tag). The App Secret itself is NEVER transmitted — it is only the HMAC signing key.

Headers

Idempotency-KeystringOptional

Request

This endpoint expects an object.
tostringRequired
fromstringOptional

Optional: if not provided, it is resolved automatically.

textstringOptional
attachmentslist of stringsOptional
Array of public URLs of attachments
status_callbackstringOptionalformat: "uri"
Optional status callback URL
mapNewNumberbooleanOptional

Optional: if true, removes existing mapping and assigns a new agent with least mappings today.

Response

Completed by agent
okboolean
dataobject

Endpoint-specific payload wrapped in a standard success envelope.

metaobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error