---
title: "Order a new iMessage sender"
method: POST
path: "/v1/imessage/senders/order"
tags: ["iMessage"]
---

# Order a new iMessage sender

`POST /v1/imessage/senders/order`

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).

## Request body

- object
  - `profileId` string, 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.
  - `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).
  - `emailName` string — Local part for email senders (required for kind: email)
  - `emailDomain` string — Domain for email senders (required for kind: email)
  - `displayName` string
  - `purchaseIntentId` string — Idempotency key for safe retries
  - `contact` object — Contact card (vCard) attached to the sender, shown when recipients save it. Required before sending with contactCard.
    - `firstName` string, required
    - `lastName` string
    - `photoUrl` string, uri

## Response `202`

Order accepted; activation continues asynchronously

- object
  - `success` boolean
  - `sender` ImessageSenderLifecycle — A provisioned iMessage sender order and its lifecycle. Activation is asynchronous: poll GET /v1/imessage/senders/{senderId} or subscribe to account.connected.
    - `id` string
    - `kind` 'phone' | 'email'
    - `region` 'US' | 'GB' | 'null', nullable
    - `handle` string, nullable — The sender handle once activation assigns it
    - `optInLink` string, nullable — imessage:// deep link that opens Messages on this sender with a prefilled text. Share it so contacts message you first (Apple only lets a sender reach contacts who wrote to it first); null until the handle is assigned.
    - `status` 'ordering' | 'activating' | 'active' | 'suspended' | 'canceled' | 'failed'
    - `priceCents` integer — Monthly price billed while the sender is active
    - `provider` string
    - `profileId` string
    - `displayName` string, nullable
    - `failureReason` string, nullable
    - `accountId` string, nullable — The messaging account created at activation
    - `createdAt` string, date-time

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `402` — A valid payment method is required (code: payment_method_required)
- `403` — Sender limit reached (code: imessage_sender_limit)
- `404` — Profile not found or access denied
- `409` — This profile already has a live iMessage sender (code: imessage_sender_conflict), or billing setup is incomplete and support must finish it (code: billing_setup_incomplete)
- `422` — Workspace is not on usage-based billing (code: usage_billing_required)
- `502` — The provider rejected the order; nothing was charged

## Changes

- **2026-09-25** `2c04683ce694` — 4 info
  - added the optional property `details/adAccountId` to the response with the `400` status
  - added the optional property `details/createdObjects` to the response with the `400` status
  - added the optional property `details/stage` to the response with the `400` status
  - added the optional property `details/unconfirmedWrite` to the response with the `400` status
- **2026-09-21** `339f59df69dd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/imessage/senders/order/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/e0122970214f?raw)