Email Parser Agent
The Email Parser Agent turns an inbound email into one normalised, structured message, so every email-driven AI Employee reads the same shape whether the mail arrived from Gmail, from Outlook, or as a raw RFC822 file.
The Email Parser Agent belongs to the Generation group in the agent library. It is its own agent type (inbound_email_parser) and makes no LLM call: parsing is deterministic. It is not a Custom agent, so there is no custom agent ID to pin. Add it from the agent library like any other agent.
When to use it
Use the Email Parser Agent as the first agent in a workflow triggered by an inbound email, whenever downstream agents need individual fields rather than the raw message:
- Extract the sender, subject, and body so an Intent Classifier Agent can route on them.
- Pull structured fields out of the body with a Data Extractor Agent that only needs the message text, not the full envelope.
- Surface attachment or URL metadata to a downstream agent that inspects what the message carried.
- Reason about whether an email is genuine, using the authentication and provenance fields described below.
Inputs
The agent takes the message in one of three formats. format selects which payload field is read.
| Input key | Required | Purpose |
|---|---|---|
format | Yes | One of rfc822, outlook, or gmail. Anything else is rejected. |
bytes | With rfc822 | The raw MIME message. Accepts a base64 string or raw bytes. |
payload | With outlook or gmail | The vendor message JSON: a Microsoft Graph message object, or a Gmail API v1 message resource. |
provider | No | Labels the mailbox source on the output: outlook, gmail, zoho, imap. Defaults to unknown. Purely a label, because parsing dispatches on format. |
{
"format": "rfc822",
"provider": "outlook",
"bytes": "RnJvbTogYWxpY2VAZXhhbXBsZS5jb20KU3ViamVjdDogT3JkZXIgIzQ4MjEgZGVsYXkKCkNhbiB5b3UgdGVsbCBtZSB3aGVuIG15IG9yZGVyIHdpbGwgc2hpcD8="
}Output
The output is one object, the same shape for every input format. Field order runs identity, then addressing, then content, then headers, then entities, then status.
| Group | Fields |
|---|---|
| Identity | message_id, internet_message_id, thread_id, received_at |
| Addressing | sender, reply_to, return_path, recipients (to, cc, bcc), from_domain |
| Content | subject, body (text, html, snippet) |
| Headers | headers.authentication_results (spf, dkim, dmarc, raw), headers.received_chain, headers.other_headers, sender_ip, dkim_selector |
| Entities | urls, attachments |
| Status | encrypted_detected, parse_errors, raw_size_bytes, provider |
| Provenance | header_provenance, auth_basis, original_message, nested_original_count |
An address is always {"email": "...", "display_name": "..."}. attachments and parse_errors are always arrays, never null, so an empty array means "none found" rather than "not checked". body.html is absent on a plain-text message.
Abbreviated example:
{
"message_id": "AAMkAGI2NGVhZTJl",
"internet_message_id": "<[email protected]>",
"received_at": "2026-08-19T09:14:22Z",
"sender": { "email": "[email protected]", "display_name": "Alice Chen" },
"recipients": { "to": [ { "email": "[email protected]", "display_name": "" } ], "cc": [] },
"from_domain": "example.com",
"subject": "Order #4821 delay",
"body": {
"text": "Can you tell me when my order will ship?",
"snippet": "Can you tell me when my order will ship?"
},
"headers": {
"authentication_results": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }
},
"urls": [],
"attachments": [],
"encrypted_detected": false,
"parse_errors": [],
"provider": "outlook",
"header_provenance": "direct",
"auth_basis": "original_sender"
}Forwarded mail. When someone forwards a message as an attachment, the authentication headers on the outer message belong to the forwarder, not to the original sender. header_provenance records where the headers came from, auth_basis says whether the SPF, DKIM, and DMARC verdicts can be trusted as the original sender's, and original_message carries the recovered inner message with the same field contract. A downstream agent should read auth_basis before trusting any authentication result.
Attachments are described, not decoded: each entry carries filename, mime_type, size_bytes, sha256, and an id the mailbox provider can use to fetch the content. Encrypted messages are flagged through encrypted_detected; the agent does not attempt decryption.
A downstream agent reads any field via {{<node_id>.output.<field>}}, for example {{<node_id>.output.body.text}} to feed the message text into a classifier, or {{<node_id>.output.sender.email}} for the sender address.
What's next
- Intent Classifier Agent — route a workflow by classifying the parsed email body.
- Data Extractor Agent — pull structured fields out of the message text.
- Send Email — send a reply once the workflow has produced one.