---
title: "Register an iMessage sender"
method: POST
path: "/v1/imessage/senders"
tags: ["iMessage"]
---

# Register an iMessage sender

`POST /v1/imessage/senders`

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.

## Request body

- object
  - `profileId` string, required — Profile to attach the sender to
  - `sender` string, required — The provider-provisioned sender handle: a phone number in international format (e.g. +18305551234) or an email address
  - `displayName` string
  - `provider` 'loopmessage' — Delivery provider. Defaults to the platform default.

## Response `200`

Sender registered

- object
  - `success` boolean
  - `account` ImessageSender — An iMessage sender registered as an account on a profile.
    - `id` string — Account id (use it with the inbox endpoints' accountId)
    - `platform` 'imessage'
    - `sender` string — The sender handle (E.164 phone or email)
    - `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).
    - `displayName` string
    - `profileId` string, nullable
    - `provider` string — Delivery provider backing this sender (e.g. loopmessage)
    - `senderVerified` boolean — Whether the provider confirmed the sender as active at registration time
    - `isActive` boolean

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `402` — A valid payment method is required (code: payment_method_required)
- `404` — Profile not found or access denied
- `409` — Sender already registered to another profile (code: imessage_sender_conflict), or billing setup is incomplete and support must finish it (code: billing_setup_incomplete)

## Changes

- **2026-09-21** `339f59df69dd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/imessage/senders/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/339f59df69dd?raw)