Skip to main content
Use /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 through POST /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 with GET /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. HTTP 202 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.