Zernio
Zernio
API Reference

iMessage

List iMessage audienceGETList instantly available iMessage numbersGETList iMessage sender ordersGETList iMessage sendersGETStart an iMessage group chatPOSTCreate a tracked iMessage opt-in linkPOSTGet an iMessage groupGETGet iMessage sender statusGETSubscribe or opt out an iMessage contactPOSTRename an iMessage group or change its photoPATCHUpdate an iMessage senderPATCHAdd a participant to an iMessage groupPOSTCancel an iMessage senderDELETEOrder a new iMessage senderPOSTRegister an iMessage senderPOSTRemove a participant from an iMessage groupDELETEReserve an available iMessage numberPOST
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
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

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

{  "success": true,  "sender": {    "id": "string",    "kind": "phone",    "region": "US",    "handle": "string",    "optInLink": "string",    "status": "ordering",    "priceCents": 0,    "provider": "string",    "profileId": "string",    "displayName": "string",    "failureReason": "string",    "accountId": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}
Was this page helpful?

Cancel an iMessage sender

Cancels the sender at the provider and deactivates its messaging account. Billing stops with the current month (no proration or refunds, matching phone numbers).

Register an iMessage sender

Registers a provider-provisioned iMessage sender (a phone number or an email handle) that YOU already own on a profile, creating an `imessage` account that sends and receives through the inbox conversation endpoints. To have Zernio order a new sender for you, use POST /v1/imessage/senders/order instead. Registration attaches the monthly sender fee (billed while active) and requires a payment method (402 without one). One sender per profile: re-registering the SAME handle refreshes it; a different handle returns 409 until the existing sender is canceled.

profileId*string
kind*string

Value in

  • "phone"
  • "email"
region?string

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

Value in

  • "US"
  • "GB"
availableNumberId?string

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

zipCode?string

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

Match^[0-9]{5}$
emailName?string

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

emailDomain?string

Domain for email senders (required for kind: email)

displayName?string
Lengthlength <= 100
purchaseIntentId?string

Idempotency key for safe retries

Lengthlength <= 100
contact?

Contact card (vCard) attached to the sender, shown when recipients save it. Required before sending with contactCard.