Email Deliverability

While we optimize for deliverability, and the vast majority of Stytch emails are delivered successfully, there are still some exceptions.

Below are some common causes of email deliverability issues:

• The email address provided is inactive or outdated.

• The recipient's email inbox is full, or the email server is otherwise rejecting incoming messages.

• The user has email security software in place that delays or blocks emails sent from email addresses or domains that aren't explicitly allowed. This is most common in enterprise settings.

Stytch emits logs with an action of EmailDelivery for email delivery events, which you can view in the Event Logs section of your Stytch Dashboard. Each log has a message_status field (displayed in the drop-down view of the log) which indicates the status of the email.

There may be more than one EmailDelivery event per email sent (grouped by identifiers like request_id and user_id) - for instance, the logs below show a MagicLinksEmailSend request with two corresponding EmailDelivery log events (one delivered and one open).

Possible message_status values are:

• delivered - The recipient's email server has acknowledged delivery of the email.
• bounce - The recipient's email server has "bounced" the email, or refused delivery and sent the email back. This can happen for a number of reasons, including the following:

  • The recipient's inbox is full.

  • The recipient's email address no longer exists or could not be found.

  • The recipient's email server is offline.

  • Automatic responses, including out-of-office replies can sometimes cause bounces.
• open - The recipient has opened the email after delivery.
  • This may appear more than once if the recipient opens the email multiple times, or if certain email client features are enabled (for example, iOS Mail Privacy Protection).
  • The absence of an open status does not necessarily mean the email was never opened - for example, if an email client blocks images from loading, opening emails will not trigger open events.

• Delays in email arrival:
   

  1. Determine whether delays are occuring for all users and email domains, or just a subset.
     • If delays are occuring for all users:
       • If you're using a custom email domain or template, you may need to optimize the content of emails and the sender domain reputation. We have a blog post around this subject here, and Postmark has some great documentation on domain reputation here.
       • If you're not using custom templates and domains, or if you are but need some additional guidance, feel free to reach out to us at support@stytch.com.

     • If this is just for one user, or a subset of users, the issue is likely related to the specific email client and security settings. Continue to step 2:

  2. Check the Event Logs for a delayed email arrival.
     • You can search Event Logs by request_id or user_id to see EmailDelivery actions pertaining to one of our email-based products.
  3. In the Event Logs, determine when the email was marked as delivered by the recipient's email server.
     • When viewing Event Logs for a particular request, click into EmailDelivery events to see the message_status and timestamps:
       • If the email was marked as delivered shortly after the Stytch API request, but the email was delayed in its arrival to the inbox, this generally means that the email was successfully delivered to the mail server but was then delayed by the mail client:
         • This can happen when the email gets "stuck" in the spam filter. If you're using a custom email domain or template, you may need to optimize the content of emails and the sender domain reputation. We have a blog post around this subject here, and Postmark has some great documentation on domain reputation here.

• Successful Stytch requests where the email doesn't appear in the user's inbox:
   

  1. Check Stytch logs for the user via the Event logs tab in the Stytch Dashboard.
     • If there's an issue preventing emails from being successfully triggered, you may see Error logs there.
     • If you don't see any requests for that user (neither Success nor Error logs), there may be something preventing Stytch endpoints from being called at all for the user. In that case, we'd recommend taking a look at your own internal application logs to pinpoint the issue. If all requests appear to be successful, there may be something preventing your user's email software from displaying Stytch emails in the user's inbox.
  2. Ask your user to check their spam folder.

     • Stytch emails aren't often marked as spam, but it can happen in rare cases. If your user does find a Stytch email in their spam folder, ask them to mark it as safe or not spam to ensure that future emails reach their inbox.

  3. Ask your user to add Stytch emails to their email sender allowlist.
     • The specific process varies by email provider, but in some cases (particularly for enterprise email addresses), the user's email administrator may need to take this action for them. One example of this is Microsoft's Tenant Allowlist.

• User hitting invalid_email errors:

  • The user's email address is improperly formatted. Ask your user to make sure that they're entering their email address correctly.

• User hitting inactive_email errors:
  • If our email provider receives a hard bounce or user-initiated spam complaint when attempting to send an email to a given email address, that email address will be marked as inactive, and future requests will result in inactive_email errors.
  • If your user has verified that their email address is correct and that they should be able to successfully receive emails, please reach out to support@stytch.com and we can reactivate the user's email address.

If you've completed the above troubleshooting steps and are still having trouble pinpointing the issue, we can check our email provider's logs and share the result with you (please reach out to support@stytch.com if interested). Note that once an email successfully reaches your user's email server, we no longer have visibility into why it didn't show up in their inbox.