Skip to content

Register releases.sh with Google so the Gmail email annotations activate #2159

Description

@zachdunn

#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

  1. 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.
  2. 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.
  3. 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.

Metadata

Metadata

Labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions