An email provider rejecting messages causes Okta to drop the emails and log a bounce failure. Administrators resolve this by using the Email Address Bounces API to remove blocked email addresses from the service.
When Okta sends an email, the receiving server sometimes rejects the message. This prevents the user from receiving password resets, new account creations, or other notifications. The receiving server drops the email, considers it a bounce, and generates a failure message in the Okta system log using the following event type: system.email.delivery.
Email delivery FAILURE: dropped
Email delivery FAILURE: Bounce
NOTE: The Email Address Bounces API is unavailable in Free Trial and Developer organizations. SuperAdmin permissions are required to perform these actions. To remove users from the Spam Reporting list, contact Okta support and specify that the request involves Spam Reporting.
- Okta Classic Engine
- Okta Identity Engine (OIE)
- Troubleshooting E-Mail Deliverability
The email provider rejects messages from Okta because the recipient's mailbox is not configured, the inbox is full, the address is invalid, or the inbox blocks Okta emails. For additional information about tracing email errors in the Okta system logs, review the Troubleshooting E-Mail Deliverability article.
How is an email address unblocked using the API?
Watch this video or follow these steps to remove an email address from the bounced email address list:
- Prepare the environment to send API calls to the Okta tenant. This example will use Postman.
- Create a POST request to the email bounce endpoint for the Okta tenant:
https://<subdomain>.okta.com/api/v1/org/email/bounces/remove-list
- To remove an address from the bounce list, enter the following code in the request body, replacing the placeholder with the target email address:
{ "emailAddresses": [ "name@company.com" ] }
NOTE: Multiple email addresses can be removed from the bounce list in a single API call by separating the addresses with commas.
- Add the following headers to ensure the request functions correctly:
- Key: Accept
- Value:
application/json
- Value:
- Key: Content-Type
- Value:
application/json
- Value:
- Key: Accept
- Send the request. A successful response returns an HTTP 200 OK status code with output indicating no errors.
NOTE: The same successful response appears regardless of whether the email address had an existing bounce. If an existing bounce is present, an asynchronous job that runs every 2 minutes removes it.
Okta recommends using OAuth 2.0 Authorization. In this case, the token needs the next scope:
okta.orgs.manageWhat possible errors could be received when unblocking an email address using the API?
When a request is sent using an email address that does not belong to the Okta organization or is not in a valid format, the following errors might be received:
- Invalid email address. The provided email address failed verification against RFC 3696.
- This email address does not belong to any user in your organization.
What event type is logged when email addresses are removed from the bounce list using an API request?
The following System Log event system.email.bounce.removal is triggered when an API request is made to remove bounced emails (POST /org/email/bounces/remove-list). This request sends a list of emails to a third-party email service to remove the emails from the bounce list. The event is triggered when the API request is made. The event does not indicate when the third-party email service actually removes the emails.
NOTE: For more information about this event type, see the Okta event type catalog.
Can unblocking bounced email addresses be automated?
For customers who have purchased Okta Workflows, these tasks can be automated by navigating to the Admin Console > Workflows > Workflow Console and searching for "Automated Unblocking of Bounced Okta Emails (via System Log Monitoring)".
NOTE: For more information, open a Support Ticket with the Okta Workflows Support Team.
