You are correct — FusionAuth can add SMTP headers under Tenant → Edit → Email → Advanced → Additional headers, but those headers apply to all emails sent for that tenant. There is currently no way to set headers per-user or per-email.

Your two workarounds are both valid approaches:

Option 1: SMTP Proxy

Route FusionAuth's outgoing SMTP traffic through an SMTP proxy or mail-relay service. Your proxy can inspect the recipient, determine their consent state, and inject the required tracking headers before final delivery.

Option 2: Webhooks + External Mailer (Recommended for full control)

Disable FusionAuth's built-in email templates and handle all email sending via webhooks to your own backend or third-party mailer. This gives you complete control over templating, state checking, and headers per user.

Webhook-based flow:

Disable the built-in email templates in FusionAuth so it doesn't send anything itself. Navigate to Tenants → Edit → Email → Templates and set each template to disabled or leave it unassigned. You can also configure this at the application level under Applications → Your Application → Email → Templates to override tenant-level settings.

Set up webhooks under Settings → Webhooks, pointing to your backend endpoint. Enable the specific events you need.

Your backend listens for events, pulls relevant data from the webhook payload, checks user consent state, and sends the email through your own mailer with appropriate headers.

Key webhook events and payloads: Email Verification: verificationId to build the verification link Forgot Password: changePasswordId to build the reset link Setup Password: check user.password is null to confirm they need setup Breached Password (user.password.breach😞 user.email to notify them to change their password Suspicious Login (user.login.suspicious😞 event.info for device and location details (Enterprise feature) Registration Verification (user.registration.verified😞 verificationId to build the verification link MFA Method Added/Removed: method object with the method type and identifier

Important: If you use the webhook approach, make sure to disable all relevant email templates in FusionAuth. If you leave some templates enabled while your third-party mailer is active, users will receive duplicate emails — one from FusionAuth and one from your mailer.

Related Documentation Configure SMTP - Custom Headers - Information on configuring tenant-level SMTP settings including additional headers Announcing FusionAuth 1.32 - Custom Email Headers - Details on the custom email headers feature added in version 1.32 Events & Webhooks - Complete documentation on FusionAuth's webhook system Email Templates - Managing and disabling email templates Application-Specific Email Templates - Overriding email templates at the application level User Login Suspicious Event - Webhook payload for suspicious login events User Password Breach Event - Webhook payload for breached password events User Registration Verified Event - Webhook payload for registration verification events

Yes, FusionAuth Cloud uses static outbound IP addresses that you can whitelist in your downstream services. The specific IPs depend on your deployment's region.

These IP addresses are static and will not change under normal circumstances. If FusionAuth ever needs to modify or add to these addresses, customers will receive advance notification.

To obtain the specific outbound IPs for your region, you'll need to open a support ticket through the FusionAuth Account portal with your deployment name and details.

Important Notes:

New deployments receive static outbound IPs by default. If you have an existing deployment created before static IPs were standard, you may need to request them via support ticket. The provided IP addresses are intended only for allow-listing outbound traffic (such as SMTP services, webhooks, LDAP connectors, etc.). These IPs should not be used to make inbound API calls, as they won't respond to such requests. Static IPs are available for all FusionAuth Cloud deployments, including both standard and High Availability (HA) configurations. Related Documentation FusionAuth Cloud - Deployment IP Addresses - Official documentation on obtaining IP addresses for your deployment FusionAuth Cloud - Support - How to access support and open tickets for IP address requests FusionAuth Cloud Overview - General information about FusionAuth Cloud hosting

The user.update.complete event intentionally does not fire when the verified flag changes through email verification. This is by design.

Email verification is considered a distinct workflow separate from the general user update process in FusionAuth's event model. As noted in a related GitHub issue, the decision was made to introduce dedicated verification events rather than triggering user.update.complete because email verification "does not occur due to the Update User API, but because of a separate workflow." The user.update.complete event is reserved for changes made through the Update User API, while verification-specific changes trigger their own dedicated events.

Recommended Solution

You should listen to these specific webhook events for verification state changes:

user.email.verified — fires when an email address is verified (available since 1.8.0) user.identity.verified — fires when an identity (email or phone number) is verified (available since 1.59.0) Handling Race Conditions

If you're concerned about race conditions when multiple events fire simultaneously:

Adjust your Kafka partitioning strategy to key on userId — this ensures all events for the same user go to the same partition and are processed in order Use event timestamps in your downstream consumers to deduplicate or order events correctly. Each event includes a createInstant field in the event object that can be used for ordering Design your sync logic to be idempotent so that processing events out of order doesn't cause inconsistent state

The separate user.email.verified and user.identity.verified events provide more granular control over what verification changes you respond to, which is generally more useful than a generic user update event.

Related Documentation User Update Complete Event — documentation for the user.update.complete event User Email Verified Event — documentation for the user.email.verified event User Identity Verified Event — documentation for the user.identity.verified event Kafka Integration — comprehensive guide to FusionAuth's Kafka integration for consuming webhook events Webhook Event Log — review events sent by FusionAuth with timing and result information

FusionAuth follows RFC 5322 for standard email validation, which defines the local part as a dot-atom. However, FusionAuth does not expose a specific custom regex for email validation—it adheres to the RFC 5322 standard.

Can you override or customize email validation?

Yes, but only partially through FusionAuth's built-in features:

You can customize validation using Customizations > Form Fields in the FusionAuth admin UI. However, if you want to completely implement your own validation logic, you would need to handle that within your own application and your own pages/API. Resources

Here are some helpful links for managing user verification and email validation workflows:

How User Verification Works Gate Accounts Until User Email Verified

If you need exact custom validation logic, you'll need to implement it on your application side and potentially use custom form fields to enforce it during registration or profile updates.

You want to modify the Two-Factor Login duration in the Tenant Settings, which applies across to SMS and MFA methods.

https://fusionauth.io/docs/get-started/core-concepts/tenants#advanced has more details.

First, ensure that Debug is enabled in your SMTP settings for the tenant. After enabling it, try sending password reset emails again and then check the Event Logs for any errors or details about why emails aren’t going out.

For more troubleshooting steps, see the FusionAuth SMTP documentation:
Configuring Email in FusionAuth

This issue may occur if the Forgot Password email template is still enabled in FusionAuth. To resolve this:

Disable the Forgot Password email template at the tenant level:
Navigate to Tenant > Edit Tenant > Email tab > Template Settings.
Set the Forgot Password template to Feature Disabled.

Check the application-specific settings:
If you have an application-specific template set up, ensure the Forgot Password template is also disabled under the Application settings.

Verify API configuration in the PHP client (if applicable):
If you’re using the PHP client, ensure sendForgotPasswordEmail is explicitly set to "false" (as a string with quotes), not just false (boolean). This ensures the value is passed correctly.
These steps should prevent FusionAuth from sending its own Forgot Password email when the API is called, resolving the double-email issue.

This issue may occur if the Forgot Password email template is still enabled in FusionAuth. To resolve this:

Disable the Forgot Password email template at the tenant level:
Navigate to Tenant > Edit Tenant > Email tab > Template Settings.
Set the Forgot Password template to Feature Disabled.

Check the application-specific settings:
If you have an application-specific template set up, ensure the Forgot Password template is also disabled under the Application settings.

Verify API configuration in the PHP client (if applicable):
If you’re using the PHP client, ensure sendForgotPasswordEmail is explicitly set to "false" (as a string with quotes), not just false (boolean). This ensures the value is passed correctly.
These steps should prevent FusionAuth from sending its own Forgot Password email when the API is called, resolving the double-email issue.

@zaalbarxx sorry for the delay. I might be missing it (sorry not a PHP person) but I don't see where that confusion comes into play. I know that some of our docs had to get updated because of a change that we made during our 1.50 release that required to request further details in our scopes request.

This release makes significant changes to the default behavior of new Applications with regard to scopes in OAuth workflows. The database migration will update existing Applications to behave in a backwards compatible manner. See the OAuth Scopes documentation for more information, in particular the Relationship, Unknown scope policy, and Scope handling policy configurations.

https://fusionauth.io/docs/release-notes/#version-1-50-0

Let me know if that still isn't making sense, or if there is a spot you were hung up on and I would be happy to update our docs. Or even better feel free to add a PR.

@apeksha-barhanpur

My apologies, I mistakenly believed you had a support plan with FusionAuth (let me know if I am mistaken).

Regarding your question --

Have you had a chance to review the troubleshooting guide that we publish for email?
https://fusionauth.io/docs/v1/tech/admin-guide/troubleshooting#troubleshooting-email

Lastly, a good tip is to remove FusionAuth completely from the email equation by using SWAKS. SWAKS will complete an email exchange with just your email provider credentials (thereby removing FusionAuth from the equation). If SWAKS fails, then would offer good troubleshooting information.
http://www.jetmore.org/john/code/swaks/

Thanks,
Josh

A couple of things:

https://fusionauth.io/docs/v1/tech/troubleshooting/#troubleshooting-email has troubleshooting tips worth checking out.

The UI copy doesn't copy the SMTP password, so double check that as well.

You want to look at https://fusionauth.io/docs/v1/tech/lambdas/samlv2-response-populate/ This can update the email/nameId before it is sent over to the special SP.

You will want to create a separate application and set the Response Populate Lambda to the lambda which does this transformation. This can be done via the UI as illustrated here: https://fusionauth.io/docs/v1/tech/samlv2/

Yes. That’s how it currently works.

We have on the roadmap a more flexible identity system but don't have a current timeline for implementation. Here's the tracking issue: https://github.com/FusionAuth/fusionauth-issues/issues/1

Ensure you are not using a reply address from @fusionauth.io; if you are this will fail our DMARC policy.

You don’t necessarily want to remove this reply address, but it should not be using our email domain. Instead it should be an address that belongs to your organization, such as no-reply@example.com. (Or, even better: customersupport@example.com--I hate when I get an email I can't reply to, myself.)

Each email template also has the option to override that default value with a different value. So you may also want to audit each email template to ensure if it is using a different From address, it is also owned by your domain.

If you are using email verification, you can check this user state within your own app. (So, don't allow the attacker to access anything until their email address has been verified.)

In version 1.27.0 you can configure a gated login flow when the user is not verified (this is a 'reactor' feature requiring a paid license). This will enforce email verification before we even redirect to your app. You can then also configure FusionAuth to delete users after N number of days if the user has not verified their email address. This can assist with build up of accounts that are not actually in use.

I tried to specify both username and email and I got this error:

{ statusCode: 400, exception: { fieldErrors: { 'user.email': [ { code: '[blank]user.email', message: 'You must specify either the [user.email] or [user.username] property. If you are emailing the user you must specify the [user.email].' } ], 'user.username': [ { code: '[blank]user.username', message: 'You must specify either the [user.email] or [user.username] property. If you are emailing the user you must specify the [user.email].' } ] }, generalErrors: [] } }

So basically I guess my best bet is to manually enforce uniqueness of username in my backend. But it could have been less cumbersome if I could delegate it to FusionAuth.

I guess what I am trying to emphasis here is the fact that just by saving username in user.data we will be able to have both username and email but applying rules such as uniqueness would require more manual labor. Cannot we just tell FusionAuth to make sure that user.data.username should be unique in that app or tenant?

Side note: Since my question is deviating from the OP I'll create a new post and reference this one.

I end up using a docker image of mailcatcher.

I use the default docker-compose.yml, but use this docker-compose.override.yml:

version: '3' services: mailcatcher: image: yappabe/mailcatcher ports: - "1025:1025" - "1080:1080" networks: - mailcatcher search: image: docker.elastic.co/elasticsearch/elasticsearch:7.8.1 environment: cluster.name: fusionauth bootstrap.memory_lock: "true" discovery.type: single-node FUSIONAUTH_SEARCH_MEMORY: ${FUSIONAUTH_SEARCH_MEMORY} ES_JAVA_OPTS: ${ES_JAVA_OPTS} # Un-comment to access the search service directly # ports: # - 9200:9200 # - 9300:9300 networks: - search restart: unless-stopped ulimits: memlock: soft: -1 hard: -1 volumes: - es_data:/usr/share/elasticsearch/data fusionauth: depends_on: - search - mailcatcher environment: SEARCH_SERVERS: http://search:9200 SEARCH_TYPE: elasticsearch networks: - mailcatcher - search networks: search: driver: bridge mailcatcher: driver: bridge volumes: es_data:

Then I configure the SMTP settings to use the hostname mailcatcher and the port 1025. I can then send email and view it in the mailcatcher interface, at localhost:1080.

Here's the relevant dockerfile: https://github.com/yappabe/docker-mailcatcher/blob/master/Dockerfile

Here's more about mailcatcher: https://mailcatcher.me/

A couple of options:

You could optionally configure a different template for each tenant so you could hard code the correct URL in each template.

You could also add the correct URL to the tenant.data and then pull it out in the template during render so you could use the same template across tenants.

If the state parameter is working well for you for other APIs, you could open a feature request in GH to add this to the API in question.

Does SendGrid indicate why they are rejecting requests? In my experience, this is generally due to invalid creds, or a “From address” with a domain that does not match your SendGrid account.

So if a default template is being used with a no-reply@fusionauth.io address you may see a runtime error such as a rejected SMTP request.

Otherwise I'd make sure the IP address is in any whitelists, or share anything else that sendgrid logs.