iMessage

Order a new iMessage sender

Changed on

Orders a NEW dedicated iMessage sender from the delivery provider. Compare with POST /v1/imessage/senders, which registers a sender you already own.

Activation

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

  • Requires usage-based billing and a valid payment method.
  • Billing starts at activation (monthly per sender, no proration).
  • When the account spend threshold is below the sender price, the first month is charged before the number is bought.
  • When the card's answer takes longer than this request, the order is returned as status: awaiting_payment. The number is ordered automatically once it is paid (usually under 5 minutes).

Retries

Pass purchaseIntentId to make retries idempotent. The provider-side order is never retried automatically.

What an ordered sender includes

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

  • Base URL
    https://zernio.com/api
  • Auth
    HTTP bearer

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. sender.status is ordering or activating when the provider has the order, awaiting_payment while the first-month charge is still being confirmed (poll the sender; it moves on by itself).

successboolean

Changes

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    7 more changes in this revision