---
title: "Create a tracked iMessage opt-in link"
method: POST
path: "/v1/imessage/senders/{senderId}/opt-in-links"
tags: ["iMessage"]
---

# Create a tracked iMessage opt-in link

`POST /v1/imessage/senders/{senderId}/opt-in-links`

Generates a per-campaign link that opens Messages on this sender with
`body` prefilled. iMessage is send-first: a sender can only message a
contact who has written to it (a send to anyone else fails with
`recipient_must_message_first`), and the contact's tap-and-send is
what opens that door.

Each link carries a unique code in place of the `[opt-in-code]`
placeholder; when the contact sends it, the resulting `message.received`
webhook (and the stored inbox message's `metadata`) has
`optIn: true` and your `parameters` under `optInParameters`, so you can
attribute the conversation to the campaign or lead that produced it.

For an untracked link, use the sender's `optInLink` instead.

## Path parameters

- `senderId` string, required

## Request body

- object
  - `body` string, required — Prefilled message text. Must contain the literal `[opt-in-code]` placeholder, e.g. "Hi! My code is [opt-in-code]".
  - `parameters` object — Custom key/values (e.g. leadId, campaign) echoed back on the opt-in message.
  - `optInCode` string — Your own code in place of the generated one (3-8 characters, no spaces or `#`, `!`, `-`). An unredeemed link lives 24 hours; re-issuing with the same code replaces it, and the earlier URL stops matching.

## Response `200`

Opt-in link created

- object
  - `success` boolean
  - `link` object
    - `id` string
    - `imessage` string — imessage:// deep link
    - `sms` string, nullable — sms: deep link for non-Apple devices
    - `whatsapp` string, nullable
    - `url` string — Hosted landing URL that picks the right scheme for the device

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — Sender not found
- `409` — The sender is not active yet

## Changes

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

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/imessage/senders/:senderId/opt-in-links/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)