Authentication · MachineMail Docs

What each check means

The From header is free text: anyone can write billing@stripe.com in it. Authentication is how a receiver learns whether the sending domain actually stood behind the message. The trust report summarizes it in four fields:

{"authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "aligned": true }}

• SPF checks that the server that delivered the message is allowed to send for the envelope sender’s domain (the Return-Path, not the From).
• DKIM checks a cryptographic signature added by the sending domain, named by the signature’s d= tag.
• DMARC checks that SPF or DKIM passed for a domain that matches the From domain, and applies the domain owner’s published policy.
• ARC carries authentication results across forwarders and mailing lists that would otherwise break SPF and DKIM.

SPF or DKIM passing on its own proves only that some domain sent the message. A phisher can pass SPF for paypa1-security.com while writing From: PayPal <service@paypal.com>. That is why alignment matters.

Where the results come from

MachineMail does not re-run DNS lookups or signature checks. It uses the results recorded by the mail service that received the message for MachineMail, and nothing the sender could have written:

1. Verdicts reported by the receiving provider. When the inbound provider reports SPF, DKIM and DMARC results alongside the message, they win. The reasons then include Authentication verdicts from <provider>.
2. The Authentication-Results header added by our receiving server. Only the topmost header carrying our receiving server’s identifier counts.
3. Nothing else. Any other Authentication-Results header, ARC-Authentication-Results and Received-SPF is ignored, because a sender can add them to a message before it reaches us. A forged header that claims dmarc=pass gets no credit.

If none of this is available, every field is none, never pass.

Results are mapped to the report’s values:

When no trusted results are found, every field is none and the reasons say No trusted authentication results. If the message carried Authentication-Results headers from other servers, the reasons also say how many were ignored. A DKIM-Signature header with no verification result is noted in the reasons but does not count as a pass.

authentication_results on the message

Every inbound message (and the message.received webhook payload) also carries the results themselves as authentication_results, the field AgentMail clients read. It comes from the same sources as the summary above, but keeps more detail:

{"authentication_results": {
  "spf": "pass", "spf_domain": "mail.linear.app",
  "dkim": "pass", "dkim_domain": "linear.app",
  "dmarc": "pass", "dmarc_domain": "linear.app"
}}

• Verdicts as recorded. spf, dkim and dmarc use the Authentication-Results vocabulary: pass, fail, none, neutral, softfail, temperror, permerror. The summary’s mapping above does not apply: a permerror stays permerror. A provider’s “nothing to evaluate” (GRAY from Amazon SES) is none; a provider check that could not run is temperror.
• Domains. spf_domain is the envelope sender domain SPF checked, dkim_domain the d= domain of the signature the verdict is about (for a pass, a passing signature, preferring one aligned with From; only for pass or fail), and dmarc_domain the From domain. When the provider’s verdicts are used, the domains come from our receiving server’s header, or for DKIM from the message’s only signing domain.
• Absent, not none. A mechanism nobody evaluated is left out. The whole field is absent on sent mail, on mail injected through the API, on mail whose results no trusted server recorded, and on messages received before the field was introduced.
• Only what speaks for the sender, as in AgentMail. spf is kept only when spf_domain aligns with the From domain (shares its organisational domain, so mail.acme.com aligns with acme.com), or with the Sender domain when From names several domains; an unaligned SPF result is withheld whatever its value, and so is a provider’s SPF verdict when no trusted header names the domain. dkim and dmarc are withheld when From names more than one domain or cannot be parsed. The summary above still records every result.
• Domains, not decisions. dkim_domain is the signing domain as written: compare it with the From domain before relying on a DKIM pass, and decide with trust.level. Do not reject mail on dmarc: fail alone, since forwarding breaks it.
• arc_sealer names the forwarder whose ARC seal the verdicts came from. MachineMail does not validate ARC chains and by default ignores ARC results (see above), so it does not send this key.

Alignment

aligned is true when a passing DKIM d= domain, or the SPF domain when SPF passed, has the same organisational domain as the From address. A DMARC pass reported by the receiving provider also counts as aligned, since DMARC itself requires alignment. The organisational domain is the registrable part: mail.acme.com aligns with acme.com, and suffixes such as co.uk are handled, so a.example.co.uk and b.example.co.uk align but example.co.uk and other.co.uk do not.

The reasons list says which domain passed and whether it aligned:

{"reasons": [
  "SPF passed for mail.linear.app",
  "DKIM passed for linear.app",
  "DMARC passed",
  "Authenticated domain aligns with From domain linear.app"
]}

How authentication feeds the verdict

Authentication affects the trust report in four places.

Level.

• Any fail in SPF, DKIM or DMARC makes the message at least suspicious.
• verified requires DMARC pass with aligned: true, plus prior correspondence or an allow-list entry. A receive allow entry also blocks every sender not on the list, so prior correspondence is the usual route.
• known requires at least one of SPF, DKIM or DMARC to pass. Mail from a domain every MachineMail organization shares (such as machinemail.dev) also needs prior correspondence with that exact address or an allow-list entry; otherwise it is unknown.
• With nothing passing and nothing else wrong, the level is unknown, and the score is capped at 0.7.

Score. The authentication component carries 25% of the score:

Classifier. Failures raise the phishing and spam probabilities (DMARC fail most, then DKIM, SPF and SPF softfail), no passing authentication raises them a little, and an aligned DMARC pass lowers them. Mail that claims to come from your own domain without passing SPF or DKIM is flagged as spoofing.

Labels. If DMARC failed, or SPF and DKIM both failed, the message gets the UNAUTHENTICATED label and a message.received.unauthenticated event. It keeps the INBOX label, but message lists hide UNAUTHENTICATED mail unless you pass include_unauthenticated=true. The MCP wait_for_message tool does not wake for it.

Mail injected through the API

Messages posted to POST /inbound/raw (which needs a key with the explicit inbound_raw permission) carry whatever headers the caller wrote. MachineMail ignores all of them: authentication is always none, so injected mail is never verified or known. The message gets received_via: "raw" and the reason Injected via API (/inbound/raw); authentication results not verified. Use it for tests and fixtures.

Common patterns