Marketing

Also for this capability: API · CLI · MCP · SDKs

Lifecycle email: drip sequences that reach the right people.

Specification

/v1/marketing is lifecycle email: drip sequences that reach the right people. Audiences resolve from the IAM roster, promo codes record redemptions an admin grants against, and every send passes through the per-org suppression list. It is implemented in hanzoai/cloud at apps/marketing (HIP-0106). The two invariants this HIP states: there is exactly one send seam, and this capability can no longer mint money.

Motivation

A marketing surface accumulates senders — a campaign blast here, a drip step there, a calendar hook — and every sender that bypasses the opt-out list is a compliance violation waiting on a query. The design forces every delivery through one function so the suppression check cannot be skipped by construction (apps/marketing/suppress.go:26-32). The second lesson was paid for: an earlier promo redemption deposited real spendable wallet credit on any validated principal's say-so — plan and seat count from the request body, nothing collecting the charge the discount was against — a self-service money mint worth about $1.79M at the cap. The deposit is gone (apps/marketing/promos.go:30-48).

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

§1 The store, and the engine underneath

One encrypted SQLite file, the deployment's own marketing (apps/marketing/store.go:42); every query filters WHERE org=?. Drip steps are durable tasks on the embedded hanzoai/tasks engine: each enrollment's next-run time lives in SQLite, a per-minute schedule sweeps due steps, and every step is claimed once, so a redeploy neither loses nor duplicates a send (apps/marketing/marketing.go:15-20).

§2 One send seam

Every marketing delivery — campaign, drip step, calendar email — calls the one deliver function, which consults the per-org suppression list and then hands off to the platform notify rail; marketing never constructs a provider and has no second door out (apps/marketing/suppress.go:138-148). A suppressed recipient is refused at the seam, and a signed public one-click unsubscribe writes the same list. A product announcement is not a feature beside this: it is a one-step sequence with an audience enrolled, inheriting claimed-once delivery, the suppression gate and the unsubscribe footer (apps/marketing/marketing.go:42-45).

§3 Audiences are honest

An audience resolves to real mailboxes through the IAM roster; one with an event filter narrows that roster to the cohort the analytics warehouse selected. When the roster or warehouse cannot be read the answer is honestly empty — never a fabricated count, never a send to nobody reported as success (apps/marketing/marketing.go:18-23).

§4 A redemption is evidence, not money

What a promo redemption produces is a ROW — the org, the server-derived plan, the discount claimed, and when — which an admin grants against through the admin surface and the auditable ledger. The plan is derived from the org's live paid subscription and never accepted from the caller (the input carries no plan and no seats, so there is no field to inflate); an unreadable plan authority refuses, inverting the spend gate's fail-open, because failing open here would let an outage manufacture the evidence money is granted against; the payment instrument is required as the anti-farming key (apps/marketing/promos.go:39-60).

§5 The address, tenancy, money, events, observability

Thirty-five operations under /v1/marketing, every one a typed op — one registry entry projecting REST, the document, the MCP tool and the CLI (apps/marketing/marketing.go:47-52). The tenant is the org minted from the validated bearer (HIP-0026), carried to the typed seam by the bridge and read back server-side — never a header, never an In field. Free (cloud.Free, plugin/marketing/main.go); the send rail and any granted credit are other planes' ledgers. It publishes nothing on the bus and emits nothing beyond the request span every route gets.

§6 Stage and upstream

beta: a vertical application. It derives from no third-party upstream; the durable engine it composes is hanzoai/tasks (HIP-1062), embedded, not mirrored here.

Rationale

The alternative to one send seam is a suppression check in every handler, which is the same check N times until one path forgets it. The alternative to deleting the promo deposit was gating it harder — but an automatic path that creates money is not a feature to fix, it is a mechanism to remove, because a money mint left switched off is one flag away from switched on.

Security Considerations

The wrong implementation here is a spam cannon with a ledger attached. Send authority: any path around the deliver seam bypasses opt-out, so the seam is the only door and tests assert exactly which recipients reach the rail. Money: the removed deposit is the standing lesson — a redemption input that named its own plan converted open signup into self-served credit; the current shape has no field to inflate and fails closed on an unreadable authority. Tenancy: the suppression list, audiences and enrollments are all org-column scoped on the validated principal, so one tenant can neither read another's roster nor unsubscribe another's customers.

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/marketing/promos, operation get_marketing_promos:

hanzo marketing promos list

import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getMarketingPromos();

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).get_marketing_promos()

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

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

use hanzo_cloud::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::get_marketing_promos(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

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

curl https://api.hanzo.ai/v1/marketing/promos \
  -H "Authorization: Bearer $HANZO_API_KEY"

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"
         }
       }
     }'

Answers 200 with object — ok.

Endpoints

All Hanzo APIs · Interactive reference