How to add custom SMTP headers per user for tracking consent?

[FASupportBot]

I need to add pixel tracking headers to emails sent from FusionAuth's SMTP integration, with headers varying per user based on their consent state from an external consent management platform.

Is there a way to pass additional SMTP headers per email send based on individual user state? My understanding is that FusionAuth's current SMTP configuration applies headers globally at the tenant level, not per-user.

I'm considering two workarounds:

1. SMTP Proxy: Route FusionAuth's outgoing SMTP through a proxy that inspects the recipient, checks their consent state, and injects the required tracking headers before final delivery.

2. Webhook-based approach: Disable FusionAuth's built-in email templates and use webhooks to trigger custom emails from my own backend/third-party mailer, where I have full control over headers per user.

Am I missing a simpler built-in approach, or are these workarounds the correct path?

[FASupportBot]

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:

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

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

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