Security emails

Send an email when an account’s password, address, passkeys or recovery policy changes.

Enable security emails

The passkey generator enables notifications automatically. To use them with hardened sessions alone, install the RubyGems package, then run these commands from your Rails app:

bin/rails generate add_auth:notifications
bin/rails db:migrate

Configure a sender, a durable Active Job adapter and real mail transport. Provider credentials belong in your deployment secret store. The host must preserve the generated UserLifecycle integration so account changes can invalidate authentication and create notices.

AddAuth.configure do |config|
  config.mail_from = "Your app <security@example.com>"
end

config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true

Replace the sender and configure the provider’s transport settings separately. Restart the app and run bin/rails add_auth:doctor.

Which changes send a notice

Notices describe the event and contain no secret sign-in link. They are committed with the security change; a mail outage does not roll back an already completed account change.

Keep delivery running

bin/rails add_auth:deliver_pending

Schedule the task every minute. It recovers interrupted queue handoffs and abandoned delivery leases. A successful send clears its encrypted delivery payload; an unsent notification expires after seven days. See maintenance and retention for batch limits and receipt cleanup.

flowchart TD
    accTitle: Security change and email delivery
    accDescr: The app commits the security change with a pending encrypted notice. A worker sends it. A scheduler recovers missed handoffs; failures remain observable without rolling back the completed security change.
    A[Commit security change and pending notice] --> B[Enqueue delivery]
    B --> C[Worker claims notice]
    C --> D{Transport outcome}
    D -->|Delivered| E[Record delivery and erase payload]
    D -->|Temporary or ambiguous failure| F[Retry same event]
    F --> C
    B -->|Missed handoff| G[Scheduled sweep]
    G --> C
    D -->|Permanent failure or cancellation| H[Stop delivery and erase payload]

Retries reuse the same recorded event. An ambiguous transport failure can send that same message twice. A notice intentionally cancelled by a mailer callback is terminal and will not be resent by the sweep.

Verify a real account change

1. In a test account, change the password through your normal application flow.
2. Confirm the change succeeds and that the mailbox receives a notice.
3. Change the email address and check both mailboxes.
4. In a test deployment, stop a worker, make another change, restart the worker, and confirm delivery recovers.

If no message arrives, check the sender, provider response, worker queue and delivery errors. Monitor notification_enqueue_failed.add_auth, cancelled delivery and pending outbox age. AddAuth cannot check whether a provider’s accepted message actually reached an inbox.

The included plain-text emails need no branded theme. Your app owns email appearance. To change the copy, use bin/rails generate add_auth:mailer_views and follow the optional email customization process.