Email relay

Send your users email without ever learning their address. Connected apps POST to a single endpoint; we deliver from noreply@auth.whisp3r.com on your behalf. Revoke = emails stop.

Why this exists

The OIDC email scope is the single biggest privacy hole in the standard auth model. Once a user's email is in a hundred databases, it's everywhere — data brokers, breach dumps, the next cold-outreach campaign. Whisp3r Auth doesn't release email addresses. If your app needs to email a user, you do it through us.

The user always sees who sent the message (your app name + icon) and can disconnect you at any time, which immediately blocks further delivery.

POST /api/relay/email

Requires the auto-granted wa:email.relay scope (every authorized app has it).

POST /api/relay/email
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

{
  "user_sub":    "the-pairwise-sub-of-the-recipient",
  "subject":    "Your weekly digest",
  "body_html":  "<p>Hi {firstName}, here's your week...</p>",
  "body_text":  "Hi {firstName}, here's your week...",
  "template":   "weekly-digest"
}

Fields:

user_sub: The pairwise sub for the recipient, as it appears in your tokens. We map back to the actual user server-side.
subject: Plain text. Max 200 chars.
body_html: HTML body. Sanitized — no scripts, no inline event handlers. {firstName} placeholders are interpolated from the user's profile (when you have the scope) or stripped.
body_text: Plain-text fallback for clients that don't render HTML. Optional but recommended — we'll derive a stripped version from body_html if omitted.
template: Optional internal label for grouping in the audit trail. Helps the user (and you) see "what kind of email is this app sending" at a glance.

Response:

{
  "ok":             true,
  "delivery_id":   "del_01H...",
  "delivered_at":  "2026-06-03T18:30:21Z"
}

What the user sees

Emails arrive from noreply@auth.whisp3r.com with your app's name in the friendly-from. The footer of every relayed message includes a "Sent through Whisp3r Auth on behalf of YourApp" line plus a one-click manage permissions link.

Rate limits

Per app, per user: 5 emails / 24 hours by default. Bulk apps (newsletters, transactional digests) can request a higher limit at registration. Hitting the cap returns 429 with a Retry-After header.

Disconnect = stop

When the user revokes your app from /dashboard/applications, the relay immediately rejects POSTs targeting that user's sub with 403 disconnected. There's no out-of-band channel preserved — the user really stopped hearing from you.

Audit trail

Every relay attempt is logged. The user sees per-app message counts in their dashboard ("YourApp sent you 14 emails in the last 30 days"). Logs retain metadata only — subject + template + timestamp; we never store the body.