Product email
Product email is for the messages your app sends about its own users'
actions — a receipt, an invite, a weekly digest — as opposed to the
email capability's hosted sign-in mail (magic links, OTPs, password
resets). The two write to separate rows of the same delivery log and never
share a proof, so turning one on tells you nothing about the other.
Sending goes directly through Scribase Mail's own SMTP relay when this
deployment has one configured (SCRIBASE_MAIL_SMTP_HOST), the same relay
hosted sign-in email already uses; otherwise it falls back to Rally Send.
Either way the request and response are the same Resend-shaped body, so
switching an existing Resend integration over is a base-URL and key change,
not a rewrite.
The mail capability slot
npx scribase add mailSends one proof message to your own account's address and records it. The
registry entry is GET /v1/capabilities:
{ "slot": "mail", "title": "Product email", "status": "live", "compat": ["38-mail:mail add"] }Per-environment state is GET /v1/organizations/{org}/projects/{project}/environments/{env}/capabilities/mail,
and turning it on is the same path with POST:
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/capabilities/mail" \
-H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"{
"slot": "mail",
"status": "live",
"state": "live",
"live": true,
"provider": "scribase",
"proof": { "kind": "partner_message", "id": "…", "at": 1731400000, "detail": "a***@example.com" },
"env": {}
}state is needs_connect with a connect_url instead, when this deployment
has neither relay configured yet — nothing is sent, and nothing is typed in
the terminal. An MCP agent gets the same answer from the capabilities_add
tool with {"slot": "mail"}; capabilities_status reads it back the same
way scribase add mail does without sending anything again.
POST .../environments/{env}/email/send
The actual send, once the slot is live. Requires an owner, admin or developer role. A Resend-shaped body:
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/email/send" \
-H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
-H "Idempotency-Key: order-4821-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": "receipts",
"to": ["buyer@example.com"],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>",
"tags": [{"name": "kind", "value": "receipt"}]
}'fromis the local part only (receipts, notreceipts@yourdomain.com); the domain is whichever relay is active.totakes one address or up to 50; every address is checked against this environment's suppression list first — an address that hard-bounced or complained before is refused with422 address_suppressed, not retried.- An
Idempotency-Keyheader makes a retry of the same send safe: the same recipient with the same key gets the same message id back and is never mailed twice; a different recipient reusing that key is409 idempotency_key_reused. - Response:
{"id": "…"}for one recipient,{"id": "…", "ids": [...]}for several. - A temporary (no-account) project may only mail its own owner; mailing
anyone else is
403 temporary_project_non_owner. 503 mail_not_configuredmeans neither relay is set up yet — same gap themailcapability slot reports asneeds_connect.
Bounces and complaints
POST /v1/rally/webhooks/transactionalPublic; the credential is Rally Send's Standard Webhooks signature
(webhook-id, webhook-timestamp, webhook-signature headers), not a
bearer token. A hard bounce or a complaint adds the address to this
environment's suppression list; a soft bounce is ignored. Both the email
and mail slots' sends check the same suppression list before every send.