Troubleshooting

Why are my emails not showing up?

The most common reason inbound emails go missing is that the sender's domain failed authentication.

Inbound emails are checked for SPF, DKIM, and DMARC authentication. AgentMail drops emails when authentication headers are present and explicitly fail. If authentication headers are missing, AgentMail still processes the email and labels it unauthenticated.

AgentMail verifies inbound email using SPF, DKIM, and DMARC authentication before delivering it to your inbox. Emails with authentication headers that explicitly fail are dropped to prevent spoofing, phishing, and spam from reaching your agents.

This is the same standard enforced by Gmail, Outlook, Yahoo, and other major email providers.

How inbound authentication works

When an email arrives, AgentMail inspects the SPF, DKIM, and DMARC verdicts provided by the receiving mail server. To be delivered as authenticated, an email must meet all of the following conditions:

  • Neither SPF nor DKIM returns a FAIL verdict
  • DMARC does not return FAIL (unless the sender’s DMARC policy is none)
  • The message passes virus scanning

If authentication headers are present and any check fails, the email is dropped. If authentication headers are missing, the email is delivered with the unauthenticated label because some legitimate senders do not include those headers.

ScenarioSPFDKIMResult
Both passPASSPASSDelivered
One passes, other unconfiguredPASSGRAYDelivered
One passes, other unconfiguredGRAYPASSDelivered
Authentication headers missingGRAYGRAYDelivered as unauthenticated
Either explicitly failsFAILanyDropped
Either explicitly failsanyFAILDropped

Emails dropped due to failed authentication are rejected without a bounce-back to the sender. The sender’s mail server may still report successful delivery because AgentMail’s servers did receive the message, but it was rejected during authentication verification. To monitor emails with missing authentication headers, subscribe to the message.received.unauthenticated webhook or WebSocket event.

Why this matters

Without these checks, anyone could send emails claiming to be from any domain. SPF and DKIM authentication proves that the sending server is authorized to send on behalf of the domain in the From address, while DMARC ties those results to the domain’s published policy. Dropping emails that explicitly fail authentication protects your agents from:

  • Spoofing: forged sender addresses impersonating trusted contacts
  • Phishing: malicious emails designed to trick your agent into taking harmful actions
  • Spam: bulk unsolicited email from unverified sources

Diagnosing missing emails

If a sender reports that their email never arrived, check whether their domain’s authentication records are configured correctly:

$# check for SPF record
$dig TXT example.com +short
$# look for a record starting with "v=spf1"

For DKIM, use MXToolbox DKIM Lookup or a similar tool. DKIM records are stored under a selector-specific subdomain (e.g., google._domainkey.example.com), and the selector name varies by email provider, so there is no single DNS query that covers all cases.

You can also use MXToolbox SPF Lookup to verify SPF records online.

If the sender’s authentication headers are missing, AgentMail will still process the email and mark it unauthenticated. If those headers are present but fail, the email is dropped by AgentMail and may be rejected by other providers as well.

What to tell the sender

The sender should configure SPF and/or DKIM on their domain’s DNS and make sure their mail provider includes authentication headers. This is not something you can fix on the AgentMail side, as the records and headers must be set up by the domain owner or their email provider.

  • Add an SPF record to authorize their mail server (e.g., v=spf1 include:_spf.google.com ~all for Google Workspace)
  • Enable DKIM signing through their email provider’s admin console
  • Consider adding a DMARC record for full authentication coverage

Most email providers have setup guides: Google Workspace, Microsoft 365, Amazon SES.

Google Workspace and internal routing

If the sender uses Google Workspace and the AgentMail inbox is on a subdomain of a Google Workspace domain, Google may route the email internally instead of sending it through external MX records. In this case, the email never reaches AgentMail’s servers at all.

For example, if the Google Workspace domain is yourcompany.com and the AgentMail inbox is on agents.yourcompany.com, Google Workspace may intercept emails to agents.yourcompany.com and deliver them internally.

How to fix: In Google Admin Console, go to Apps > Google Workspace > Gmail > Routing and add a routing rule that sends mail for the AgentMail subdomain to the external MX records instead of handling it internally.

Still not receiving emails?

If the sender’s domain does have SPF/DKIM configured and emails are still not arriving:

If none of the above resolves the issue, reach out in our Discord support channel or email support@agentmail.cc.