# Create enroll

URL: https://docs.hanzo.ai/docs/openapi/marketing/post-marketing-sequences-by-id-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 →](https://docs.hanzo.ai/docs/openapi/marketing) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                           |
| ------------- | --------------------------------------------------------- |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo marketing sequences enroll <id>
```

**SDK**

**.ts**

```ts
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>" });
```

**.py**

```python
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>")
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

```bash
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**

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:

```bash
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](https://docs.hanzo.ai/docs/openapi/marketing) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)