Senders

A sender is the unit you buy: one dedicated number, on one profile, that becomes an imessage account in the inbox. Zernio orders it from the delivery provider on Apple-registered infrastructure; iMessage cannot run on a number you already own with Zernio, because Apple only registers numbers hosted by the provider.

Order a number

POST /v1/imessage/senders/order with the profile, kind: "phone" and a region of US or GB. Every ordered number comes with SMS/RCS fallback with call forwarding and the ability to message contacts who have not written first.

{
  "profileId": "68a1…",
  "kind": "phone",
  "region": "US",
  "purchaseIntentId": "order-2026-09-21-1",
  "contact": { "firstName": "Acme", "lastName": "Support", "photoUrl": "https://cdn.example.com/acme.png" }
}

The response is 202 with the sender's lifecycle object in ordering or activating. Activation is asynchronous: poll GET /v1/imessage/senders/{senderId} or listen for the account.connected webhook, which carries the new account id. Billing starts at activation.

Always send a purchaseIntentId. The provider-side order is never retried automatically, and a repeated call with the same intent id returns the existing order instead of buying a second number.

Instant activation

Some numbers are pre-registered with the provider and activate the moment you order them. List them with GET /v1/imessage/senders/available-numbers?region=US; each item has an id, the phone and, when known, a location such as a US state. Pass the id as availableNumberId on the order:

{ "profileId": "68a1…", "kind": "phone", "region": "US", "availableNumberId": "779d18a4-…" }

To hold a number while the buyer decides, call POST /v1/imessage/senders/available-numbers/{numberId}/reserve first: the hold lasts 3 minutes. The pool is a snapshot and changes over time; when it is empty for a region (the UK, at the time of writing), order without availableNumberId and the carrier assigns a number at activation, usually within a few hours. A US order without a picked number can carry a zipCode to ask for a number near that area.

Email senders

kind: "email" with emailName and emailDomain orders a sender that appears as an email address (for example support@yourbrand.com). The dashboard sells numbers only; email senders are ordered through the API and behave the same in the inbox.

Register a sender you already own

If you hold a sender with the provider directly, POST /v1/imessage/senders attaches it to a profile without ordering anything. It carries the same monthly fee while active. One sender per profile: registering the same handle again refreshes it, a different handle returns 409 until the existing sender is canceled.

Lifecycle and settings

• GET /v1/imessage/senders/order lists every sender your team owns with its status: ordering, activating, active, suspended, failed or canceled.
• GET /v1/imessage/senders/{senderId} adds the provider's live view: platform health (active, degradation, outage) and the provider-hosted imessageLink, a web page that opens Messages on the sender from any Apple device.
• PATCH /v1/imessage/senders/{senderId} changes the display name and the contact card (name and square photo) recipients see when they save the number. The contact card is also what a contactCard send shares, so set it before using that option.
• DELETE /v1/imessage/senders/{senderId} cancels the sender at the provider and deactivates the account. Billing stops with the current month, with no proration or refund, like phone numbers.

Errors