scribasedocs

Control API /v1

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

Terminal
npx scribase add mail

Sends one proof message to your own account's address and records it. The registry entry is GET /v1/capabilities:

JSON
{ "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:

Terminal
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/capabilities/mail" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"
JSON
{
  "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:

Terminal
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"}]
  }'
  • from is the local part only (receipts, not receipts@yourdomain.com); the domain is whichever relay is active.
  • to takes 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 with 422 address_suppressed, not retried.
  • An Idempotency-Key header 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 is 409 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_configured means neither relay is set up yet — same gap the mail capability slot reports as needs_connect.

Bounces and complaints

POST /v1/rally/webhooks/transactional

Public; 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.