Topics tagged with smtp

How to handle intermittent email failures with MessagingException in FusionAuth?

FASupportBot — Invalid Date

This MessagingException: Exception reading response error is often related to network issues or SMTP timeout configuration. Here's how to address it:

Check and Adjust SMTP Timeout Settings

The default SMTP timeout in FusionAuth is 2 seconds, which may be too short if your SMTP provider experiences occasional network slowness. You can increase the timeout by:

Navigate to Tenants > [Your Tenant] > Edit > Email > Advanced In the Additional properties field, add or adjust these configuration values: mail.smtp.timeout=5000 mail.smtp.connectiontimeout=5000

This increases the timeout to 5 seconds. Adjust the value as needed based on your SMTP provider's typical response times. The Additional properties field can contain any Java mail property, and these values will override FusionAuth's defaults.

Email Retry Policy

FusionAuth does not have a built-in retry mechanism for failed email sends. FusionAuth connects directly to your configured SMTP server at the tenant level without using a local mail queue. If an email fails to send due to a connection issue or timeout, FusionAuth will not automatically retry it.

Additional Troubleshooting Steps

Enable SMTP Debug Logging: In your tenant's Email settings, enable the Debug enabled option. This will provide detailed SMTP transaction logs in the FusionAuth event log, which can help identify the root cause of intermittent failures.

Review Event Logs: Check System > Event Log for error events. FusionAuth always creates an event log entry of type "Error" when it cannot send an email.

Send Test Emails: Use the Send test email button in Tenants > [Your Tenant] > Email to verify your SMTP configuration under different conditions.

Implementing Your Own Retry Logic

To handle retries, you can set up a webhook-based solution:

Configure a webhook for the event-log.create event Monitor events delivered to your webhook endpoint When you detect a MessagingException event, trigger an API call to the appropriate endpoint (e.g., /api/user/forgot-password for password reset emails) Important: Implement retry limits in your script to avoid infinite loops with invalid email addresses

This approach gives you full control over retry logic, backoff strategies, and error handling for failed email deliveries.

Related Documentation Configure SMTP - SMTP Settings - Complete SMTP configuration guide Tenants - SMTP Settings Form Fields - Details on the Additional properties field and how to customize Java mail properties Troubleshooting Email - Comprehensive email troubleshooting guide Event Log Create Event - Documentation on the event-log.create webhook event for monitoring errors Start Forgot Password Workflow API - API endpoint for triggering password reset emails programmatically

What are the outbound IP addresses for a FusionAuth Cloud deployment?

FASupportBot — Invalid Date

For FusionAuth Cloud deployments, you can obtain the outbound IP address list by opening a support ticket in the FusionAuth Account Portal and providing your deployment hostname.

Key facts about FusionAuth Cloud outbound IPs:

Complete list: FusionAuth will provide the complete list of outbound IP addresses for your specific deployment. These are the only addresses your deployment will use. Note that IP addresses are not exposed through the user interface—opening a support ticket is the only way to obtain them.

Static addresses: The outbound IP addresses are static and will not change during:

Upgrades Maintenance windows Normal scaling operations

For new FusionAuth Cloud deployments, static IP addresses are already configured. If the IP addresses ever need to change, FusionAuth will notify you in advance.

All outbound traffic: All outbound traffic from your FusionAuth Cloud deployment originates from the same set of IP addresses, including:

SMTP/email traffic Webhooks HTTP calls from Lambdas Any other outbound connections

You can safely use these IP addresses to configure firewall rules, SMTP server allowlists, and other security restrictions for services that need to accept connections from your FusionAuth Cloud deployment.

Important: The provided IP addresses should only be used to allow outbound traffic through firewalls and network control layers. Do not use them for HTTP/API calls, as they won't respond to such requests. In addition to IP allowlisting, consider using custom headers, TLS transport, and client certificates to further secure outbound traffic.

Related Documentation Deployment IP Addresses - Official documentation on obtaining IP addresses for FusionAuth Cloud deployments FusionAuth Account Portal - Support - How to access the support portal to request IP addresses FusionAuth Cloud Overview - General information about FusionAuth Cloud deployments

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

FASupportBot — Invalid Date

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