#2157 shipped Gmail annotations on every transactional email, but they are inert until releases.sh is registered with Google. The markup is correct and harmless everywhere else — Gmail simply ignores it for unregistered senders — so nothing is broken, but nobody gets the benefit either.
What's already in place
- Go-To Action (
ViewAction) on every message with a CTA — account mail (verify, magic link, password reset, email change, invitation, submission ack) and the follow digest. Renders as a button beside the subject in the inbox list.
- One-Click Action (
ConfirmAction + HttpActionHandler) on email verification, handled by POST /v1/email-actions/verify-email. Gmail POSTs the token straight from the inbox and the reader never opens the message. The handler is anonymous by design, per-IP rate limited, idempotent, and answers 2xx for every token-bearing outcome so a Google retry can't report failure for a verification that already happened.
Emitted by renderEmail() in packages/rendering/src/email-shell.ts (see actionMarkup). Details: docs/architecture/emails.md → Gmail annotations.
What's needed
- Confirm the sending domains pass DKIM, SPF, and DMARC. Auth mail sends from
noreply@releases.sh (AUTH_EMAIL_FROM) and digests from digests@releases.sh (DIGEST_EMAIL_FROM), both over Cloudflare Email Sending.
- Submit the sender registration form. Google wants a consistent volume of authenticated mail from the domain, so this is likely worth doing after the digest has been sending for a while.
- Test with the markup tester before and after — it validates the JSON-LD independently of registration.
Verifying afterwards
/admin/emails renders every message including its JSON-LD, so the payloads can be inspected without sending. Once registered, the one-click path is the one to watch: logEvent emits email-actions/verify-ok and verify-noop, so a working annotation should show verify-ok events with no corresponding page view.
#2157 shipped Gmail annotations on every transactional email, but they are inert until
releases.shis registered with Google. The markup is correct and harmless everywhere else — Gmail simply ignores it for unregistered senders — so nothing is broken, but nobody gets the benefit either.What's already in place
ViewAction) on every message with a CTA — account mail (verify, magic link, password reset, email change, invitation, submission ack) and the follow digest. Renders as a button beside the subject in the inbox list.ConfirmAction+HttpActionHandler) on email verification, handled byPOST /v1/email-actions/verify-email. Gmail POSTs the token straight from the inbox and the reader never opens the message. The handler is anonymous by design, per-IP rate limited, idempotent, and answers 2xx for every token-bearing outcome so a Google retry can't report failure for a verification that already happened.Emitted by
renderEmail()inpackages/rendering/src/email-shell.ts(seeactionMarkup). Details: docs/architecture/emails.md → Gmail annotations.What's needed
noreply@releases.sh(AUTH_EMAIL_FROM) and digests fromdigests@releases.sh(DIGEST_EMAIL_FROM), both over Cloudflare Email Sending.Verifying afterwards
/admin/emailsrenders every message including its JSON-LD, so the payloads can be inspected without sending. Once registered, the one-click path is the one to watch:logEventemitsemail-actions/verify-okandverify-noop, so a working annotation should showverify-okevents with no corresponding page view.