Sign in
iMessage

Order a new iMessage sender

Orders a NEW dedicated iMessage sender from the delivery provider (compare with POST /v1/imessage/senders, which registers a sender you already own). Activation is asynchronous (minutes to a few hours): the response is 202 with the lifecycle object; poll GET /v1/imessage/senders/{senderId} or subscribe to the account.connected webhook. Billing starts at activation (monthly per sender, no proration). Requires usage-based billing and a valid payment method. Pass purchaseIntentId to make retries idempotent — the provider-side order is never retried automatically. Ordered phone senders include SMS/RCS fallback with call forwarding and the ability to message contacts who have not written first (sending intervals still apply).

post/v1/imessage/senders/order

Request body

profileIdstring required
kind'phone' | 'email' required
region'US' | 'GB'

Required for phone senders. Without availableNumberId the number is carrier-assigned in this region and revealed once the sender activates.

availableNumberIdstring

A number from GET /v1/imessage/senders/available-numbers. It is assigned and activated on order instead of waiting for provisioning. Phone senders only.

zipCodestring

US phone senders only. Preferred area for a carrier-assigned number (ignored with availableNumberId).

emailNamestring

Local part for email senders (required for kind: email)

emailDomainstring

Domain for email senders (required for kind: email)

displayNamestring
purchaseIntentIdstring

Idempotency key for safe retries

Response

Order accepted; activation continues asynchronously

successboolean

Changes