# Taifa Mail

Taifa Identity's owned enrollment flow connects the Go admission service to Management's transactional worker and Taifa Mail. The worker encrypts queued invitation payloads, submits Mail, polls the known message ID, and acknowledges delivery for the exact admission and generation. The Mail API credential stays in the server-side Management worker. Recovery and security message journeys, genuine holder acceptance, and production rollout remain release work.

Mail delivery supports a workflow but does not prove a person's identity or make an approval effective. A delivered notice is separate from invitation redemption, required factor verification, signed activation, current workforce eligibility, and product acknowledgment. The historical provider mail adapter remains a migration artifact.

## Configure delivery

Set `MAIL_API_URL` to an approved HTTPS origin only, `MAIL_API_KEY` to the Identity worker's private credential, and `MAIL_FROM_ADDRESS` to an approved allocated sender. The worker appends `/v1/emails/`; do not include that path in the origin setting. Keep the key on the server. It sends `Authorization: Bearer ...` and `X-Client: taifa-identity`, supplies the configured `from_` address, and forces `track_opens: false`.

Mail must authorize the machine key for `emails:send` and the sender's Institution for `sending:compose`. Status polling also needs the key owner's `analytics:view` permission. A key that authenticates without these sender permissions cannot complete delivery.

## Interpret a send

The API can return HTTP 202 with a message ID and `queued`, `sent`, `delivered`, or even `rejected` status. `queued` means accepted for processing, not delivered. The worker stores the Mail ID and polls its status. It distinguishes `accepted`, `delivered`, `failed`, and `ambiguous`. A malformed response or uncertain submission must be reconciled using the known ID where possible. Mail has no request-level idempotency contract for this send, so retrying an unknown submission blindly can duplicate an authentication message.

An invitation or recovery workflow remains incomplete when required delivery fails. Existing password plus TOTP and passkey sign-in can continue during a Mail outage. Production acceptance needs a dedicated key, sender, permissions, feedback configuration, and a real approved recipient journey.

## Mail workforce login

Mail's workforce product is a separate OIDC relying party. Its mobile and desktop profiles have fixed reviewed callback schemes, `openid profile email workforce-login` scopes, and a Mail API audience. The backend must validate the access token's issuer, audience, expiry and scope, then check the local officer account, current eligibility, assigned mailboxes, and Institution. It creates its own session keyed by issuer and subject. The generic native loopback example is not one of those fixed profiles, and the owned issuer has not registered these clients yet.