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.