# Create subscribe

URL: https://docs.hanzo.ai/docs/openapi/marketing/post-marketing-subscribe

> Asks for the brand's newsletter for an address and answers 202 pending.

`POST /v1/marketing/subscribe`

> [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/subscribe` |
| **Method**    | `POST`                                        |
| **Operation** | `post_marketing_subscribe`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`        |

Asks for the brand's newsletter for an address and answers 202
pending. Nothing is recorded: the address is mailed a link to confirm, good for
seven days, and only a press on it subscribes. The answer is the same for an
address that is new, already subscribed or unsubscribed, and each is mailed
alike, so the answer says nothing about the address; one that unsubscribed gets
the link too, which is how it comes back. No account is needed, and nothing is
told to the sales mailbox or stated to an ad platform.

A deployment whose brand cannot hold the newsletter answers 503, a caller past
ten requests in an hour 429, a body over 4 KiB 413, a missing or malformed email
400, and an address already sent three links today, or a deployment past its
hourly ceiling, 429, in that order.

## Request

3 fields, body `application/json` (required).

| Field    | In   | Type   | Required | Description                                                           |
| -------- | ---- | ------ | -------- | --------------------------------------------------------------------- |
| `email`  | body | string | —        | Email is the address to subscribe.                                    |
| `locale` | body | string | —        | Locale is the reader's language as a BCP 47 tag, such as en or pt-BR. |
| `source` | body | string | —        | Source is where the form was, such as hanzo.ai or hanzo.ai/blog.      |

## Response

| Status    | Body                   | Meaning  |
| --------- | ---------------------- | -------- |
| `202`     | marketing.Subscription | accepted |
| `default` | problem-details        | refused  |

`202` body — 1 field.

| Field    | In   | Type   | Always | Description                                                                                                                      |
| -------- | ---- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `status` | body | string | —      | Status is "pending" from subscribe: a link to confirm is on its way, and the answer is the same whatever the address's standing. |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo marketing subscribe create
```

**SDK**

**.ts**

```ts
import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postMarketingSubscribe({ email: "<email>", locale: "<locale>" });
```

**.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_subscribe(email="<email>", locale="<locale>")
```

**.go**

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

resp, _, err := client.MarketingAPI.PostMarketingSubscribe(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_subscribe(&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).postMarketingSubscribe();
```

The method above is the one at the current release of the document. `hanzoai@8.5.914` (npm) and `hanzoai@8.5.914` (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. [SDKs →](https://docs.hanzo.ai/docs/sdks)

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/marketing/subscribe \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "email": "<email>",
       "locale": "<locale>"
     }'
```

**MCP**

MCP reaches **marketing** through the `marketing` tool, which names its 82 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)