API Recipes

Each recipe does one common task from start to finish. The reference pages list every parameter. These recipes show which parameters go together.

All requests need an API token. See API Authentication.

The unsubscribe link, by type of email

The email you send decides the unsubscribe link, not the template. Use this table to find the setting for each type of email.

Email	Where to turn the link off	Default
Confirmation from an opt-in form	The form’s Include unsubscribe link in confirmation email setting, or `automation_settings.include_unsubscribe_link_in_confirmation: false`	On
Confirmation from the subscribers API	`double_opt_in: { include_unsubscribe_link: false }`	On
Confirmation from the transactional API	Nothing to do	Off
Sequence step	The step’s `include_unsubscribe_link: false`	On
Transactional email	Nothing to do. Send `include_unsubscribe_link: true` to add the link	Off
Broadcast	Keep it on. A marketing email must have an unsubscribe link	On

An email sent with the link off gets no channel footer, no unsubscribe link and no List-Unsubscribe header. A footer block in it shows its company and address, but no unsubscribe link.

An email sent with the link on always has an unsubscribe link. If its footer block hides the link, and the email has no {{ unsubscribe_url }} link of its own, Broadcast adds the channel footer. A marketing email cannot go out without an unsubscribe link by mistake.

Double opt-in from an opt-in form, with no unsubscribe link

Use this recipe when people sign up through a Broadcast opt-in form on your website.

Open the form and click Settings. Under Automation, turn on Double opt-in.
Uncheck Include unsubscribe link in confirmation email, and click Save.
Optional: in the confirmation template, use a footer block with Show unsubscribe link off. The confirmation then shows your company and address.

With the API, update the form’s automation settings:

PATCH /api/v1/opt_in_forms/123

{
  "opt_in_form": {
    "automation_settings": {
      "double_opt_in": true,
      "include_unsubscribe_link_in_confirmation": false
    }
  }
}

The setting applies to every confirmation that this form sends.

Use this recipe when your own website or app collects the email address, and Broadcast sends the confirmation.

Step 1. Create a confirmation template. The template must have template_purpose: "confirmation", or the subscribers API refuses it with a 422. Put {{ confirmation_url }} in a button, and use a footer block with showUnsubscribe: false:

POST /api/v1/templates

{
  "template": {
    "label": "Signup confirmation",
    "subject": "Please confirm your subscription",
    "template_purpose": "confirmation",
    "content_type": "blocks",
    "blocks_json": {
      "version": 1,
      "blocks": [
        { "type": "text", "props": { "html": "<p>Click the button to confirm your subscription.</p>" } },
        { "type": "button", "props": { "label": "Confirm", "href": "{{ confirmation_url }}" } },
        { "type": "footer", "props": { "company": "Acme Inc.", "address": "1 Main Street, Springfield", "showUnsubscribe": false } }
      ]
    }
  }
}

You do not need html_body_add_footer. If you send false, Broadcast changes it to true and the response carries a parameter_overridden warning. This does not add the link to the confirmation. The send controls the link, in step 2.

Step 2. Create the subscriber with double opt-in, and turn the link off:

POST /api/v1/subscribers

{
  "subscriber": {
    "email": "jane@example.com",
    "first_name": "Jane"
  },
  "double_opt_in": {
    "confirmation_template_id": 456,
    "include_unsubscribe_link": false
  }
}

The subscriber stays unconfirmed until they click the link. Without confirmation_template_id, Broadcast sends the channel’s default confirmation template. See Subscribers API.

Double opt-in with your own email content

Use this recipe when you want to write the confirmation email in the request, with no template. The transactional API sends it with no unsubscribe link by default.

POST /api/v1/transactionals

{
  "to": "jane@example.com",
  "subject": "Please confirm your subscription",
  "body": "<p>Hi {{ first_name }}, please <a href=\"{{ confirmation_url }}\">confirm your subscription</a>.</p>",
  "double_opt_in": true,
  "subscriber": { "first_name": "Jane" }
}

Broadcast creates the subscriber if it does not exist. See Transactional Email API.

A receipt or password reset

Use this recipe for an email that a person needs, whether or not they subscribe to your marketing. Transactional emails have no unsubscribe link by default.

POST /api/v1/transactionals

{
  "to": "jane@example.com",
  "template_id": 789,
  "subject": "Your receipt for order 1001"
}

The template gives the body. subject replaces the template’s subject. Leave out template_id and send subject and body to write the email in the request.

A welcome sequence after confirmation

Use this recipe to send a series of emails after someone confirms. Sequence emails are marketing, so keep the unsubscribe link on.

Step 1. Add a send_email step to the sequence:

POST /api/v1/sequences/12/steps

{
  "sequence_step": {
    "action": "send_email",
    "label": "Welcome",
    "parent_id": 1,
    "subject": "Welcome to Acme",
    "body": "Hi {{ subscriber.first_name }}, thanks for joining.",
    "include_unsubscribe_link": true
  }
}

Step 2. Enroll subscribers. For an opt-in form, set the form’s sequences. A subscriber is enrolled after they sign up, or after they confirm when double opt-in is on. Only active sequences enroll subscribers:

PATCH /api/v1/opt_in_forms/123

{
  "opt_in_form": {
    "automation_settings": { "sequence_ids": [12] }
  }
}

To enroll one subscriber directly:

POST /api/v1/sequences/12/add_subscriber

{
  "subscriber": { "email": "jane@example.com", "first_name": "Jane" }
}

See Sequences API.

Use this recipe to send one email to many subscribers. A broadcast always has an unsubscribe link. A footer block with Show unsubscribe link on gives it your design. With no footer block, Broadcast adds the channel footer.

Step 1. Create the broadcast:

POST /api/v1/broadcasts

{
  "broadcast": {
    "subject": "October news",
    "content_type": "blocks",
    "segment_ids": [34],
    "blocks_json": {
      "version": 1,
      "blocks": [
        { "type": "heading", "props": { "text": "October news" } },
        { "type": "text", "props": { "html": "<p>Here is what changed this month.</p>" } },
        { "type": "footer", "props": { "company": "Acme Inc.", "address": "1 Main Street, Springfield" } }
      ]
    }
  }
}

Step 2. Send it now, or schedule it:

POST /api/v1/broadcasts/321/schedule_broadcast

{
  "broadcast": {
    "scheduled_send_at": "2026-11-03 09:00",
    "scheduled_timezone": "America/New_York"
  }
}

To send it now, use POST /api/v1/broadcasts/321/send_broadcast. See Broadcasts API.

Move subscribers from another platform

Use this recipe to import a list without sending a confirmation to people who already confirmed.

People who already confirmed: send confirmed_at. This needs an admin API token. A channel token ignores the field and returns a warning.

POST /api/v1/subscribers?broadcast_channel_id=1

{
  "subscriber": {
    "email": "jane@example.com",
    "confirmed_at": "2024-06-01T10:00:00Z"
  }
}

People who unsubscribed: send unsubscribed_at. Any API token can do this. Broadcast stores them as unsubscribed in the same request, and sends them nothing.

POST /api/v1/subscribers

{
  "subscriber": {
    "email": "sam@example.com",
    "unsubscribed_at": "2025-03-14T09:30:00Z"
  }
}

See Subscribers API.

Read the warnings

A response can carry warnings when Broadcast ignores or changes a value you sent. Read them while you build an integration. See API Response Warnings, and API Response Warnings for the unsubscribe link.