Enroll API

POST /api/enroll

JSON body. email and provenance.source are required. sequenceId is an optional UUID — omit it to use the workspace default sequence. Tags merge onto the contact.

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -H 'x-enrollmill-workspace: you@company.com' \
  -d '{
    "email": "casey@example.com",
    "sequenceId": "11111111-1111-1111-1111-111111111111",
    "tags": ["trial"],
    "provenance": {
      "source": "usagemill.overage",
      "eventId": "evt_01HQ",
      "mill": "usagemill"
    }
  }'

200 returns { ok, enrollmentId, contactId, sequenceId, status, idempotent }. Invalid JSON or payload is 400. If CostSlice reports that tenant unprofitable, the response is 409 with Paused — tenant looks unprofitable in CostSlice. A thin tenant stays paused until hitl.approve is approve. Forcing an unprofitable tenant requires hitl.approve of force and an actor. Same-event retries that already enrolled skip this check.

Workspace (no Bearer key in v0)

Auth is soft. There is no API key header yet. Resolution order:

1. Signed-in session cookie, if present.
2. Optional header x-enrollmill-workspace (email). Looks up an existing workspace — it does not create a user.
3. Otherwise the first existing user in the database. No fallback mint.

Idempotency

When provenance.eventId is set, retries with the same workspace + event return the existing enrollment and idempotent: true. Without an event id, the key is workspace + email + sequence + source.

Stop on reply, bounce, or unsubscribe

These are not log-only stubs. A matching contact's latest enrollment becomes replied, bounced, or unsubscribed. Queued send jobs for that enrollment are marked stopped. The send worker refuses further sends. Reply timeline entries store the reply text.

curl -s -X POST $APP_URL/api/webhooks/bounce \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","reason":"mailbox full"}'

curl -s -X POST $APP_URL/api/webhooks/reply \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","text":"not now — maybe later"}'

curl -s -X POST $APP_URL/api/webhooks/unsubscribe \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","reason":"please stop"}'

Bounce and unsubscribe return { ok: true, recorded: true, stopped, contactId, enrollmentId }. Reply is classified as inbound: the sequence stops, then a summary plus two draft variants land on /approvals. Nothing sends until a human approves.

POST /api/webhooks/inbound

Resend inbound (Media Yard dogfood). Accepts Resend email.received JSON or a simple { from, to, subject, text, messageId } body. Idempotent on workspace + Message-ID. Classify:

• reply — stop the sequence, then Approvals pending. BYO LLM writes the summary plus Short / Helpful drafts when a key is present; otherwise a stub summary and a manual composer. Never auto-send.
• bounce / unsub — stop only. No AI drafts.
• other — timeline only. v1 drafts are reply-only.

curl -s -X POST $APP_URL/api/webhooks/inbound \
  -H 'content-type: application/json' \
  -d '{
    "from": "casey@example.com",
    "to": "you@yourproduct.com",
    "subject": "Re: your trial is live",
    "text": "not now — maybe later",
    "messageId": "<unique@example.com>"
  }'

If RESEND_WEBHOOK_SECRET / inbound env is missing, the route still accepts JSON and signed-in /approvals can simulate a reply. IMAP poll is out of v1. No Slack notify, no hosted LLM, no LinkedIn or SMS.

GET /api/health

curl -s $APP_URL/api/health
# {"ok":true}

CSV or enroll API

Both paths are first-class. Import a file you already have, or enroll on provenance.eventId.

Mill recipes

Media Yard mills enroll through the same API external customers get.

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"costperjob.job_closed","eventId":"evt_01HQ","mill":"costperjob"}}'

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"usagemill.overage","eventId":"evt_01HQ","mill":"usagemill"}}'

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"webhookmill.signed","eventId":"evt_01HQ","mill":"webhookmill"}}'

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"mentionmill.known_mention","eventId":"evt_01HQ","mill":"mentionmill"}}'

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"costslice.spend_spike","eventId":"evt_01HQ","mill":"costslice"}}'

curl -s -X POST $APP_URL/api/enroll \
  -H 'content-type: application/json' \
  -d '{"email":"casey@example.com","provenance":{"source":"askforstars.happy_path","eventId":"evt_01HQ","mill":"askforstars"}}'