# 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

```sh
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`:

```sh
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:

```sh
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.
