Create enroll

Adds one contact or a whole audience to a sequence and schedules the first step for each.

POST /v1/marketing/sequences/{id}/enroll

Marketing → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/marketing/sequences/{id}/enroll`
Method	`POST`
Operation	`post_marketing_sequences_by_id_enroll`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Adds one contact or a whole audience to a sequence and schedules the first step for each. The sequence must be ACTIVE (a draft sends nothing), and the request must name exactly one of address or audienceId.

Enrolling is ALL this does: the message itself is sent later by the drip engine, through the suppression gate, so an opted-out customer can be enrolled here and still never be mailed. Re-posting is safe — an address this sequence already took is counted in alreadyEnrolled and never double-dripped — which is what makes retrying a partially-applied announcement a resume rather than a second send.

Request

5 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the sequence id from the path.
`address`	body	string	—	Address is a single recipient, normalized (lower-cased, trimmed) before use.
`audienceId`	body	string	—	AudienceID fans the sequence out over a saved audience, resolved live to the org's mailable customers.
`channel`	body	string	—	Channel is the delivery surface; empty means email.
`id`	body	string	—	ID is the sequence id from the path.

Response

Status	Body	Meaning
`200`	marketing.EnrollResult	ok
`default`	problem-details	refused

200 body — 4 fields.

Field	In	Type	Always	Description
`alreadyEnrolled`	body	integer (int64)	—	AlreadyEnrolled is how many this sequence had already taken and were left alone.
`enrolled`	body	integer (int64)	—	Enrolled is how many started a walk on this call.
`enrollmentId`	body	string	—	EnrollmentID names the walk, and is present ONLY for a single-address enroll — a fan-out has many, and reporting one of them would be a lie.
`resolved`	body	integer (int64)	—	Resolved is how many addresses the request named — 1 for an address, the audience's deliverable count for an audience.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo marketing sequences enroll <id>

.ts

.py

.go

.rs

.java

import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postMarketingSequencesByIdEnroll({ id: 'id', address: "<address>", audienceId: "<audienceId>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketingApi(client).post_marketing_sequences_by_id_enroll(id='id', address="<address>", audience_id="<audienceId>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.MarketingAPI.PostMarketingSequencesByIdEnroll(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, marketing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = marketing_api::post_marketing_sequences_by_id_enroll(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketingApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new MarketingApi(client).postMarketingSequencesByIdEnroll();

curl -X POST https://api.hanzo.ai/v1/marketing/sequences/<id>/enroll \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "address": "<address>",
       "audienceId": "<audienceId>"
     }'

MCP reaches marketing through the marketing tool, which names its 35 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_marketing_audiences"
         }
       }
     }'

Marketing API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousRedeem promos NextCancel enrollments