← Back to guides

Authentication email delivery for links users must receive

Authentication email delivery sends time-sensitive magic links, email-verification links, password-reset links, and organisation invitations created by the auth engine. A reliable path authenticates server requests, rate-limits abuse, queues work, retries temporary failures, and records delivery state without logging the auth URL or token.

Keep token creation separate from sending

Own Auth creates and stores the one-time token, builds the allowed application URL, and later verifies the token. An email provider or Own Auth Delivery receives the finished URL and sends it. Delivery must not create users, consume tokens, or create sessions.

auth.ts
import {
  createOwnAuth,
  OwnAuthManagedEmailProvider,
} from "own-auth";

export const auth = createOwnAuth({
  tokenPepper: process.env.OWN_AUTH_TOKEN_PEPPER,
  baseUrl: "https://app.example.com",
  emailProvider: new OwnAuthManagedEmailProvider({
    deliveryKey: process.env.OWN_AUTH_EMAIL_DELIVERY_KEY,
  }),
});

Protect the delivery request path

  1. Accept requests only from trusted server code using a server-only delivery credential.
  2. Validate the email type, recipient, and allowed auth URL shape.
  3. Rate-limit by delivery key, recipient, and application quota.
  4. Queue accepted work instead of holding the HTTP request open.
  5. Retry only failures known to be temporary and keep processing idempotent.

Model delivery states accurately

  • Accepted: the provider accepted the message for processing.
  • Delivered: the recipient server accepted the message.
  • Failed: a final rejection, bounce, complaint, suppression, or provider failure was reported.
  • Queued or retrying: the service still owns work that has not reached a final state.

Do not report an accepted API response as inbox delivery. Process provider callbacks idempotently and suppress recipients after permanent bounces or complaints so one application's traffic does not damage sender reputation.

Design templates for authentication decisions

  • Name the application and the requested action clearly.
  • Show the expiry without exposing internal token details.
  • Use one prominent HTTPS action link.
  • Explain what to do when the recipient did not request the action.
  • Keep marketing content out of transactional authentication email.

Measure reliability without collecting secrets

Track counts and latency from request acceptance to provider acceptance and final delivery events. Segment by safe application ID, email type, and status. Investigate spikes in rate limits, bounces, complaints, and retries without copying message bodies or auth links into analytics.