Okta uses SendGrid as its primary outbound email service. When email protection services within an organization are not blocking emails, delivery failures may still occur due to bounces, blocks, or deferrals. Okta provides admins with visibility into email delivery events through the Okta System Log and API to identify and resolve these issues.

Admins may observe that Okta-generated emails, such as activation or password reset emails, are not reaching 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 is cleared. 

The following four statuses appear in delivery events:

Email bounces may 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 is cleared.

A bounce message typically contains the following information:

• The time and date the message bounced
• The mail server that bounced the message
• The 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.

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 to track email delivery events in the Okta System Log

The following steps explain how to use the Okta System Log to monitor email delivery for a specific user.

• To identify all email delivery events for a specific user, use the following filter in the System Log:

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

• To identify failed email delivery events, use the following filter:

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

How to identify bounces in the Okta System Log

1. To identify a potential bounce, access the System Log and use the following filter:

   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 is considered bounced.

How to clear email bounces using an Okta API call

The following steps explain how to examine bounce details and clear the bounce using the Okta API.

1. Examine the Provider Message in the Debug Data. This message shows the exact reason the email is listed as bounced and may indicate an error with the recipient's email server that requires resolution to address broader delivery issues.
2. Once the error or condition is cleared from the recipient's email server, clear the bounce from SendGrid using one of the following resources:

• • Unblocking an Email Address From the Okta Email Address Bounce List Using the API
  • Remove bounced emails

NOTE: If the API call cannot be completed, 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"