For AI agents: The complete documentation index is available at /docs/llms.txt. A markdown version of this page is available at /docs/email.md.

Email

Edit on GitHub
View Markdown
On this page

This section explains email and email templates in FusionAuth. Email Templates provide a way to customize the content and appearance of email sent from FusionAuth.

In order to use email templates and email based workflows, you must first configure an SMTP server.

For additional information on integrating directly with the email APIs, see Email APIs.

Understand Email Security#

Email service providers (ESPs) such as Gmail, Yahoo Mail, and Proton Mail rely on several methods to prevent spam and phishing emails from being sent to their users. As of 2024, these methods have become even stricter. Google requires SMTP providers to allow users to send only from their own registered domains to reduce spam.

Here are the ways ESPs implement email security:

  • Rate limits: Emails that are received too frequently or show sudden spikes in volume are blocked.
  • IP address block lists: Emails received from dynamic IP addresses, those known to send spam, or those with a low reputation are added to lists that receivers use to reject mail.
  • DNS records of email senders: Emails must have valid records for Sender Policy Framework (SPF) (RFC 7208), Domain Keys Identified Mail (DKIM) (RFC 6376), and Domain-based Message Authentication, Reporting, and Conformance (DMARC) (RFC 7489).

SPF, DKIM, and DMARC are TXT records you need to add to the DNS records for your domain. Your SMTP provider will tell you what records to add.

  • An SPF record looks like v=spf1 ip4:129.6.100.200 ip6:2610:20:6005:100::20 -all and lists the IP addresses permitted to send email on behalf of the domain. ESPs should reject emails arriving from an IP address other than these.
  • A DKIM record looks like k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQ8c7wIDAQAB and specifies a public key. The SMTP provider will sign the sender address of an email with the corresponding private key. ESPs should reject emails with an invalid sender address signature.
  • A DMARC record looks like v=DMARC1; p=none; rua=mailto:rua@dmarc.brevo.com and specifies the policies supported by the email sender and where to send rejected email for analysis by the sender.

Together, these three records allow an ESP to know that the email server and sender are valid and what responses the sender supports if an invalid email is received.

You might also encounter the term Author Domain Signing Practices (ADSP), an optional extension to DKIM that enables a domain to publish the signing practices it adopts when relaying mail on behalf of associated authors.

Which Provider To Choose?#

An SMTP provider is an online service that sends email on your behalf. In return for payment, an SMTP provider guarantees you a service that provides IP addresses with a high reputation.

Some providers are easy to test, requiring nothing more than registering with an email address. Others require comprehensive company details, your verified phone number, domain verification, having a professional business website, and communicating with support agents. The easiest providers to configure are:

  • MailerSend — Requires only an email address.
  • Gmail — Requires phone verification, and email is intended only for small tests. Not for production use.
  • AWS SES — Requires email and domain verification.
  • Postmark — Requires email and domain verification.
  • Resend — Requires email and domain verification.

Postmark had especially clear documentation and an easy setup experience.

The more difficult providers are:

  • Brevo
  • Mailgun (Sinch)
  • SendGrid (Twilio)

These providers automatically disable your account on signup and require you to contact their support to have it activated. This involves having a business website ready for review, explaining what your purpose in sending email is, and explaining how you obtained your recipients' email addresses. However, Mailgun and Brevo support were friendly and quick, and unlocked the FusionAuth test account after reasonable discussion. SendGrid is the most onerous provider, with full company details needed for every sender address.

The worst provider is Mailchimp (Mandrill). Mailchimp was the only SMTP provider that refused to provide FusionAuth an account, giving no explanation and accusing us of sharing prohibited content. Mailchimp support was poor — entirely automated, and no human could be contacted.

Be aware that providers can cancel your account at any time, without explanation or a chance to appeal. This can cripple your business.

Choose an SMTP provider that you feel is trustworthy.

When comparing pricing, note that some providers charge a flat monthly fee, and some charge only for the number of emails you send. One provider might be cheaper than another for small volumes of email, but more expensive for large volumes.

Can You Use A Self-Hosted SMTP Server?#

It is possible to send email through an SMTP server hosted on your server using an application like Postfix, Haraka, mailcow, or Mail-in-a-Box. Hosting your own server will cost you nothing more than a few dollars a month for a cloud server, or nothing if you already have a server for other applications.

However, over time, hosting your own SMTP server will almost certainly cost you more time and money than paying a dedicated email company to handle mail for you. Below are some things you'll need to handle if you want to self-host:

  • Deliverability: Email service providers block or filter emails from dynamic IP addresses and untrusted servers. You need to maintain IP reputation, implement SPF, DKIM, and DMARC properly, and handle feedback loops with ESPs (bounces and spam requests).
  • Scalability: As email volume grows, you need to scale your infrastructure.
  • Technical expertise: Properly configuring and maintaining an email server requires understanding both the software and the network infrastructure. You need to continuously monitor your server and ensure it is available with 100% uptime.
  • Security: Your server must be secured against unauthorized access and data must be protected against breaches, requiring regular security audits and updates.

Using your own SMTP server is appropriate if you are using FusionAuth for a hobby project or a small team where all users know to check their spam folders.