diff --git a/docs/email-delivery-brevo.md b/docs/email-delivery-brevo.md new file mode 100644 index 00000000..f0ffa369 --- /dev/null +++ b/docs/email-delivery-brevo.md @@ -0,0 +1,16 @@ +# Email Deliverability Setup (Brevo & Outlook Junk Prevention) + +## Overview +Default Firebase Authentication verification emails lack custom domain authentication and branded styling, causing aggressive filtering algorithms (especially Microsoft Outlook / Exchange / Office 365) to route verification emails to Junk. + +## Solution Architecture +1. **Custom SMTP / Transactional Email Provider**: We integrate Brevo (`https://api.brevo.com/v3/smtp/email`) to send HTML branded verification messages with domain signing. +2. **Domain Authentication Requirements**: + - **SPF**: Add `include:spf.brevo.com` to `mobilitydatabase.org` TXT records. + - **DKIM**: Add the DKIM TXT key provided in Brevo Domain Settings (`mail._domainkey.mobilitydatabase.org`). + - **DMARC**: Set a standard DMARC policy (e.g. `v=DMARC1; p=none; rua=mailto:dmarc@mobilitydata.org`). +3. **Environment Variables**: + - `BREVO_API_KEY`: API key from Brevo console. + - `BREVO_SENDER_EMAIL`: Verified sender address (e.g. `no-reply@mobilitydatabase.org`). +4. **Client Guidance**: + - The user verification page informs users to inspect their Junk/Spam folder and explicitly mark messages from `mobilitydatabase.org` as "Not Junk". diff --git a/src/app/[locale]/verify-email/PostRegistration.tsx b/src/app/[locale]/verify-email/PostRegistration.tsx index 26775780..46ba31b4 100644 --- a/src/app/[locale]/verify-email/PostRegistration.tsx +++ b/src/app/[locale]/verify-email/PostRegistration.tsx @@ -80,6 +80,11 @@ export default function PostRegistration(): React.ReactElement { account registration. Please also check your junk or spam folder if you do not see it in your inbox. + + Using Microsoft Outlook or a corporate email? Verification emails may + land in your Junk folder. If found there, please mark the message as + "Not Junk" to ensure future notifications arrive safely. +