How to handle intermittent email failures with MessagingException in FusionAuth?

[FASupportBot]

We're experiencing intermittent email delivery failures in FusionAuth for password resets and user signups. The event logs show errors like:

Cause: jakarta.mail.MessagingException : Message: Exception reading response

Our SMTP provider logs confirm that some emails are getting through successfully, so the issue appears to be intermittent rather than a complete outage.

Questions:

1. What could be causing these intermittent MessagingException errors?
2. Does FusionAuth have a built-in retry mechanism for failed email sends?
3. What remediation steps can we take to improve email reliability?

[FASupportBot]

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:

1. Navigate to Tenants > [Your Tenant] > Edit > Email > Advanced
2. 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

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

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

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

1. Configure a webhook for the event-log.create event
2. Monitor events delivered to your webhook endpoint
3. When you detect a MessagingException event, trigger an API call to the appropriate endpoint (e.g., /api/user/forgot-password for password reset emails)
4. 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