Okta uses SendGrid as the primary outbound email service. When email protection services within an organization do not block emails, delivery failures still occur due to bounces, blocks, or deferrals. Administrators resolve Okta email delivery issues by identifying bounce events in the System Log and clearing them through the API. Okta-generated emails, such as activation or password reset emails, fail to reach end users.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Multi-Factor Authentication (MFA)
• Email
• Activation

Okta sends outbound email through SendGrid. When a recipient's mail server permanently rejects a message, SendGrid adds the address to a bounce list and stops attempting future delivery to that address until the bounce clears.

The following four statuses appear in delivery events:

Email bounces occur for any number of reasons. A bounce means the message is undeliverable and the address is in an indefinite undeliverable state. When a bounce occurs, the mailer receives an automatic delivery failure notification originating from the recipient's mail server. Once SendGrid adds an address to the bounce list, it stops attempting to deliver current and future messages until the bounce clears.

A bounce message typically contains the following information:

• The time and date the message bounces
• The mail server that bounces the message
• The Request for Comments (RFC) code and reason for the bounce

NOTE: According to RFC standards, hard bounces use a 5XX code and soft bounces use a 4XX code. Not all Internet Service Providers (ISPs) consistently adhere to these codes, so exceptions may occur.

Track email delivery status in the Okta System Log by filtering for specific users and delivery events, and clear email bounces using the Okta API by examining the provider message and removing the bounce condition.

This 5-minute video explains how to track email delivery status in the Okta System Log and how to clear email bounces using the Okta API. 

How does the Okta System Log track email delivery events?

Track email delivery events for a specific user by applying specific filters in the Okta System Log.

• Identify all email delivery events for a specific user by entering the following filter in the System Log:
  

  target.id eq "user@domain.com" and eventType eq "system.email.delivery"

• Identify failed email delivery events by entering the following filter in the System Log:
  

  target.id eq "user@domain.com" and eventType eq "system.email.delivery" and outcome.result eq "FAILURE"

How does the Okta System Log identify bounces?

Identify bounces in the Okta System Log by filtering for failed delivery events and examining the debug data for a provider message.

1. Access the System Log and enter the following filter to identify a potential bounce:

   target.id eq "user@domain.com" and eventType eq "system.email.delivery" and outcome.result eq "FAILURE"

2. Expand the event details down to DebugData to check for a Provider Message. A Provider Message is typically present for bounces and provides additional details on why the message bounces.

How does an Okta API call clear email bounces?

Clear email bounces using an Okta API call by examining the provider message in the debug data and removing the bounce condition from the recipient's email server.

1. Examine the Provider Message in the DebugData. This message shows the exact reason the email bounces and indicates an error with the recipient's email server that requires resolution to address broader delivery issues.
2. Clear the bounce from SendGrid using the API once the error or condition clears from the recipient's email server.

NOTE: If the API call fails, contact Okta Support and include the email address that requires clearing.

Related References

• Active Directory Activation Emails Not Sending
• Emails using custom email sender are not being received by gmail accounts
• Delivered, Bounced, Blocked, and Deferred Emails: What Does It All Mean?
• Unblocking an Email Address From the Okta Email Address Bounce List Using the API
• List of IP Addresses that Should be Allowlisted for Processing Email Delivery
• Email Delivery FAILURE: Bounce Due to "451 Internal resource temporarily unavailable"