/send when you need to send a 1:1 text message or native voice note to a phone number or
Apple ID email handle. Use Create a chat when you need a
durable chat.id, attachments by URL, or chat history. Use Create a
group for group chats.
Request
Response
Fields
Voice notes
Voice notes use a separate two-step workflow: stage genuine CAF or uncompressed WAV throughPOST /api/v1/voice-notes, then send the temporary
voice_note_id from the exact phone_line_id returned by staging. The staged
ID expires after 15 minutes and is invalidated by a phone-line service restart.
Voice-note sends must not include body, attachments, effect, or
rich_link; send companion content separately. See Voice notes
for format requirements, complete cURL/JavaScript/Python examples,
idempotency guidance, and troubleshooting.
Message text & line breaks
Responses and message history echo the normalized text, not the raw bytes you sent. The same rules apply to
body here and to text parts[].value on the chat routes.
Attachments
/send accepts three reference shapes interchangeably. Upload first via POST /api/v1/attachments, then reference the returned attachment_id:
Effects
Set"effect": "<name>" to attach an Apple send-effect (the same fullscreen / bubble effects you get from Messages on iOS). Effects are whitelist-validated upstream — an unknown value returns 4098 UNKNOWN_EFFECT with the full allowed_effects array in the error body, so callers can self-discover the current set.
Behavior
Delivery failures
/send does not use the enveloped { success, error, trace_id } shape documented in Errors. Failures return a flat object:
/send failure responses do not carry a trace_id. The enveloped { success: false, error: {...}, trace_id } shape belongs to the other /api/v1 routes.
Retrying sends
When a result has been saved, repeating the same request with the same key returns that result, even if it failed. It does not initiate another attempt. Some failures occur before a result is saved. Concurrent requests and a lost response after dispatch can therefore cause duplicate sends, even with the same key. A new key starts a new send and can also duplicate delivery. If delivery is uncertain, check the message status withGET /api/v1/messages/{id} and the conversation history before sending again. Do not treat retryable: true as proof
that a send did not happen. A future change is planned to improve retry and
idempotency behavior; it is not available yet.
Common errors
See the full error code reference.
See also
Pending sends and line-enabled SMS retry
On lines enabled for automatic SMS retry, eligible plain-text phone messages may retry once as SMS after a confirmed iMessage failure. Email recipients, groups, media and iMessage-only features are excluded. See Retrying sends before repeating a request. HTTP202 with status: "queued" means the outcome is pending. Poll
GET /api/v1/messages/{message_id} using the returned message ID. A final result
reports the observed service (imessage or sms). sent does not imply
recipient delivery; delivered is true only when delivery was observed. Use
polling for pending retry results; do not assume a final webhook will follow.
A send still pending 24 hours after the request reports status: "failed" with
code 4103 (delivery_unknown).
Code 4104 means the original send failed and the SMS retry failed or was
unavailable. It is non-retryable. Code 4103 means the outcome is uncertain;
do not start a new send with a different key merely because a request timed out.
