iMessage

To use iMessage you order a sender of your own, registered with Apple, from the API or the dashboard. When it is ready it shows up as an imessage account, and its chats live in the Inbox next to WhatsApp, SMS and social DMs. People without iMessage still get your message, as SMS or RCS from the same number.

This page is the platform summary. Numbers, porting and compliance for other channels are in Phone, SMS & voice.

#What you can do

#Connect

A sender is one dedicated number (or email address) on one profile. iMessage cannot run on a number you already have elsewhere, because Apple only registers numbers hosted for this service. You need a payment method on file and usage-based billing first.

curl -X POST https://api.pozy.ai/v1/imessage/senders/order \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "kind": "phone",
    "region": "US",
    "displayName": "Acme Support",
    "purchaseIntentId": "order-acme-support-1"
  }'

const res = await fetch("https://api.pozy.ai/v1/imessage/senders/order", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "66a1f0c2a4b9d3e8f1a2b3c4",
    kind: "phone",
    region: "US",
    displayName: "Acme Support",
    purchaseIntentId: "order-acme-support-1",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.sender.id, data.sender.status);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/imessage/senders/order",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
        "kind": "phone",
        "region": "US",
        "displayName": "Acme Support",
        "purchaseIntentId": "order-acme-support-1",
    },
)
sender = resp.json()["sender"]
print(sender["id"], sender["status"])

You get 202 back, with the sender ordering or activating. Activation finishes later on its own: check Get iMessage sender status from time to time, or listen for the account.connected webhook, which includes the new account id. You are billed from the moment it is active.

Update an iMessage sender sets the display name and the contact card (name and square photo) people see when they save the number. Cancel takes the sender offline at once and stops the next month's charge. One sender per profile.

#Sandbox

Before you order, try iMessage on the shared sandbox line for free:

1. Add your own phone number or Apple ID email with Add an iMessage sandbox contact. It starts pending.
2. From that phone, send the returned joinText (for example JOIN 4821) to the sandbox line. joinLink opens Messages with it filled in.
3. The contact turns active. Everything you send to the line now arrives in your inbox and fires your webhooks.

The handle must be the one your device starts new conversations from (iPhone: Settings, Apps, Messages, Send & Receive). Sandbox rules: up to 5 contacts per user, a 24-hour reply window after the contact's last message, 50 messages a day, no starting conversations, no groups, and no verification codes, prices or marketing. It is free and does not count as a connected account.

#Bring contacts in

The safest way to start is to let the contact write first. It needs no pacing, has no content rules and records consent.

• Each sender has an optInLink (an imessage:// link with prefilled text) and an imessageLink web page that opens Messages from any Apple device, useful in email.
• Create a tracked iMessage opt-in link returns imessage, sms and whatsapp links plus a hosted url that picks the right one for the device. When the contact sends the message, message.received carries metadata.optIn: true and your parameters in metadata.optInParameters, so you can attribute the conversation. Unused links expire after 24 hours.

An inbound STOP (also STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) opts the contact out and skips automations for that message. START, UNSTOP or SUBSCRIBE opts them back in. List iMessage audience lists everyone who has messaged your senders with their subscribed state, and Subscribe or opt out changes it on your side.

#New contacts

An ordered sender can message someone who never wrote to it, with Create conversation. Apple shows these messages with a Report Junk button, and reports can block a sender for good, so Pozy enforces the rules before anything is sent.

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "participantId": "+13105551234",
  "message": "Hi Chris, this is Sam from Northwind Builders. I build websites for contractors. Would you like to see a couple of examples?"
}

A send past a limit gets 429 new_contact_limit, together with the time you may try again. Write like a person talking to one other person. Sales pitches, made-up deadlines and anything that looks like a mass mailing get flagged by recipients. Watch your reply rate, and stop writing to someone who has left three messages unanswered. As soon as a contact answers, the limits no longer apply to that chat.

#Sending messages

Replies use the same Send message call as every channel, with the sender's accountId:

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "message": "Your table for four is confirmed for *Friday at 8pm*.",
  "subject": "Booking confirmed",
  "effect": "confetti"
}

subject, effect, contactCard and channel only work on iMessage and return 400 elsewhere. Typing indicators and read receipts work inside an active two-way conversation.

#Limits

Past the edit or unsend window, the calls return 409 edit_window_expired or unsend_window_expired.

#Inbox

Inbound messages fire message.received. metadata includes the channel the message arrived on, the message type, the reply thread id, a detected language, the transcript of a voice message and any rich-text markup as markdownText. Inbound media is copied to Pozy storage so the links keep working. Apple's six tapbacks render natively, other emoji are sent as custom tapbacks (iOS 18 and later), and inbound reactions arrive as reaction.received.

Group threads arrive as their own conversation with isGroup: true. Start one with Start an iMessage group chat (asynchronous; the thread appears with the first group webhook), and rename it or add and remove people with the group endpoints.

#Pricing

A sender has a flat monthly fee, charged at activation and on the 1st of each month while it is active, with no per-message fee. Its imessage account also counts as a connected account. The first month and any month already started are not refundable. See Pricing for current prices.

#Errors you may see

Errors covers the error format.

#Endpoints

#Webhook events