Opt-in & Audience
Opt-in links and tracked links that open Messages on your sender, STOP and START handling, and the audience list
The best way to start an iMessage relationship is to let the contact send the first message: it needs no pacing, it works from any Apple device, and it records consent. Every sender exposes links that do exactly that.
Opt-in links
Each sender's optInLink (on GET /v1/imessage/senders and on the lifecycle object) is an imessage:// deep link that opens Messages on the sender with a prefilled text. GET /v1/imessage/senders/{senderId} also returns imessageLink, a web page hosted by the provider that opens Messages from any Apple device; use it where a scheme link would not work, such as an email.
Tracked links
POST /v1/imessage/senders/{senderId}/opt-in-links creates a link that carries your own parameters back:
{
"body": "Hi Acme! My code is [opt-in-code]",
"parameters": { "campaign": "spring-sale", "leadId": "L-1042" },
"optInCode": "ACME42"
}The response has an imessage link, an sms link for Android and older iOS, a whatsapp link, and a hosted url that picks the right scheme on the device. The [opt-in-code] placeholder is replaced with a unique code (or your optInCode, 3 to 8 characters). When the contact sends that message, the resulting message.received webhook has metadata.optIn: true and your parameters under metadata.optInParameters, so the conversation can be attributed to the campaign or lead that produced it. An unredeemed link lives 24 hours; re-issuing with the same code replaces it.
STOP and START
An inbound STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) marks the conversation opted out, mirrors the opt-out to the provider, and skips automations for that message. START, UNSTOP or SUBSCRIBE opts the contact back in, as does a message sent through an opt-in link. A send to an opted-out contact returns 409 with recipient_opted_out; the inbox also re-checks the provider's suppression list before messaging a thread that has been quiet for more than a day.
Audience
GET /v1/imessage/audience lists every 1:1 contact who has messaged your senders, newest activity first, with subscribed, the last message and, for threads opened through a tracked link, the opt-in time and parameters. Filter by accountId, status (subscribed or unsubscribed) and search.
POST /v1/imessage/audience/subscription opts a contact out or back in for one of your senders. It is scoped to your account; a business-side opt-out never changes what the contact has with other businesses, so only the contact's own STOP is mirrored to the provider.