Transactional email, incidents, and notifications.
Transactional email
OAuth sign-in setup
Sign-in and sign-up share the GitHub, Google and Microsoft authorization-code flow with PKCE and a short-lived HTTP-only state cookie. Provider credentials stay server-side. Set each provider's <PROVIDER>_CLIENT_ID and <PROVIDER>_CLIENT_SECRET to enable its button. OAuth is disabled in hosted Preview, consistent with the separate Preview account configuration.
For Microsoft, register an application in Microsoft Entra ID with Accounts in any organizational directory and personal Microsoft accounts as its supported account type. Add a Web platform redirect URI:
- Production:
https://getratchet.app/api/account/oauth/microsoft/callback. - Local development:
http://localhost:3000/api/account/oauth/microsoft/callback, matchingNEXT_PUBLIC_APP_URLexactly.
Set MICROSOFT_CLIENT_ID to the application (client) ID and MICROSOFT_CLIENT_SECRET to the client secret value, not its secret ID. Keep its expiry in the operator's rotation schedule. The integration uses the common v2 authority and the delegated openid email profile scopes; it does not request mailbox access or offline refresh tokens. Configure account email before enabling new Microsoft registrations. A work/school tenant may require administrator consent under its own policy.
Microsoft identities are keyed by the immutable, application-specific UserInfo sub; email and usernames never identify or automatically merge accounts. Microsoft does not assert email_verified, so a new registration sends GetRatchet's normal 30-minute verification link and creates its workspace only after verification. A repeated sign-in before verification returns to the confirmation notice; users can enter their email and use Resend verification email for an expired or missing link. An account with a matching existing email must sign in by its current method and link Microsoft from Profile. Linked identities can sign in even when Microsoft subsequently omits or changes the email claim. If Microsoft supplies no usable email for a new identity, create an email account first, verify it, then link Microsoft from Profile.
See Microsoft's authorization-code flow, UserInfo endpoint, and identity claims guidance.
Email delivery
GetRatchet uses Resend for account and operational email. Set RESEND_API_KEY in the server environment. All messages use GetRatchet <no-reply@getratchet.app> as the sender and contact@getratchet.app as Reply-To, defined in lib/email-addresses.ts; legacy EMAIL_FROM settings are ignored. Verify getratchet.app in Resend, publish the DNS records it requests, and ensure the Vercel and maintenance-worker sending keys permit this domain before deploying. A key restricted to another domain will not deliver these messages. Never expose the API key to the browser. Without the key, sends report Email provider is not configured and account verification cannot complete.
Public contact links use contact@getratchet.app. Configure a Cloudflare Email Routing rule for this exact address to a verified inbox owned by the operator. Email Routing forwards mail to that inbox; it does not provide a mailbox login or automatically allow replying as contact@getratchet.app. Verify the destination and test incoming delivery before considering contact mail operational. If inbound mail is already hosted elsewhere, preserve that provider's MX records and create the contact mailbox or alias there instead.
lib/email.ts centralizes sending and branded HTML/plain-text templates. The development-only /email-preview page displays sample messages without sending them. Account messages contain short-lived links and security advice. Operational templates contain only organization, service/project context, a short summary, and an internal details link. Never include API credentials, agent inputs, outputs, prompts, full errors, or signed URLs in an email.
The sender should have working DKIM and SPF records, a suitable DMARC policy, and a monitored reply address. Test delivery to major mailbox providers after the domain and key are configured. Provider errors are reduced to status codes in application responses; do not log response bodies, request headers, or full recipient addresses. Alert failures must be handled outside the execution transaction.
Operational incidents
The Incidents page keeps versioned records for worker absence, circuit openings and recoveries, exhausted steps, and completed recovery scheduling. Owners and admins choose event types and verified organization members as recipients. Alerts are disabled until configured. Every event remains in the organization history even if email is disabled, grouped, or fails. Repeat events for the same target within ten minutes are grouped for email; the history still records each event.
Email is attempted after the execution transaction commits. A failed send cannot change the tool result. The independent platform-maintenance worker retries failed sends (with customer polling as a configurable fallback), at most three attempts, with an increasing delay; the incident shows the final notification state. Delivery is at least once if a process stops after sending but before storing the receipt. Do not use these emails as an exact-count audit source.
Worker absence is detected after five minutes without heartbeats. The independent platform-maintenance worker checks stale workers even when all customer workers are offline. Customer polling is a fallback unless PLATFORM_MAINTENANCE_POLL_FALLBACK=false. Monitor the maintenance service itself externally; if both maintenance and customer polling stop, detection stops too. See platform maintenance. The public status page reports platform availability separately from customer worker health.