Create invites

POST /v1/marketing/beta/invites

Marketing → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/marketing/beta/invites`
Method	`POST`
Operation	`post_marketing_beta_invites`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Reserves an invite for each address the limits admit and answers the message the member's mailbox sends for each: subject, text and HTML, the unsubscribe headers, with the member's referral link for that invite and a one-click unsubscribe for that address. Nothing is sent from here; the member's browser sends each from their own Gmail and reports it to POST /v1/marketing/beta/invites/sent.

An address is skipped, with why, when it is not an email address, is the member's own, cannot be invited (it opted out of the brand's email, its company did, the platform bars it, or it already holds an account: one reason for all, so no one learns which), was invited in the last 30 days, or is past the member's 20 a day or 100 a month. When the limits leave the member nothing to reserve the answer is 429, with Retry-After the seconds until a slot frees.

Request

1 field, body application/json (required).

Field	In	Type	Required	Description
`to`	body	string[]	—	To is the addresses to invite, at most 50.

Response

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

200 body — 13 fields.

Field	In	Type	Always	Description
`invites`	body	marketing.BetaInvite[]	—	Invites are the reserved invites, each with its message.
`invites[].headers`	body	object	—	Headers are the headers the message carries beside its own: the one-click unsubscribe (RFC 8058), List-Unsubscribe and List-Unsubscribe-Post.
`invites[].headers.*`	body	string	—
`invites[].html`	body	string	—	HTML is the same message as HTML.
`invites[].id`	body	string	—	ID is the invite's id: the link's utm_content and what the sent report names.
`invites[].link`	body	string	—	Link is the member's referral link for this invite.
`invites[].subject`	body	string	—	Subject is the message's subject.
`invites[].text`	body	string	—	Text is the message's plain text, its unsubscribe line last.
`invites[].to`	body	string	—	To is the invited address.
`left`	body	integer (int64)	—	Left is how many more the member may invite now: the smaller of what is left today and what is left this month.
`skipped`	body	marketing.BetaInviteSkip[]	—	Skipped are the addresses not reserved.
`skipped[].to`	body	string	—	To is the address as given.
`skipped[].why`	body	string	—	Why is the reason: not an email address, your own address, this address cannot be invited, you already invited this address, daily limit reached, monthly limit reached, or too many in one request.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo marketing beta invites 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.postMarketingBetaInvites({ to: ["<to>"] });

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_beta_invites(to=["<to>"])

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

resp, _, err := client.MarketingAPI.PostMarketingBetaInvites(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_beta_invites(&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).postMarketingBetaInvites();

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/beta/invites \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "to": [
         "<to>"
       ]
     }'

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 sent NextCreate request