Create subscribe

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

POST /v1/marketing/subscribe

Marketing → · All API references → · Get started →

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.

Examples

CLI

SDK

HTTP

MCP

hanzo marketing subscribe create

.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.postMarketingSubscribe({ email: "<email>", locale: "<locale>" });

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

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
}

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

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. [email protected] (npm) and [email protected] (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 →

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 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:

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?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate confirm NextCreate suppressions