# 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`](/imessage/list-imessage-senders) and on the lifecycle object) is an `imessage://` deep link. It 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`](/imessage/create-imessage-opt-in-link) creates a link that carries your own parameters back:

```json
{
  "body": "Hi Acme! My code is [opt-in-code]",
  "parameters": { "campaign": "spring-sale", "leadId": "L-1042" },
  "optInCode": "ACME42"
}
```

The response has four links:

- `imessage`
- `sms`, for Android and older iOS
- `whatsapp`
- 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`. The conversation can then 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`) does three things:

- marks the conversation opted out
- mirrors the opt-out to the provider
- 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`](/imessage/list-imessage-audience) lists every 1:1 contact who has messaged your senders, newest activity first. A contact you [messaged first](/platforms/imessage/new-contacts) appears once they reply.

Each entry has `subscribed` and the last message. Threads opened through a tracked link also have the opt-in time and parameters.

Filter by `accountId`, `status` (`subscribed` or `unsubscribed`) and `search`.

[`POST /v1/imessage/audience/subscription`](/imessage/set-imessage-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.