Skip to main content

Email Automations

Trigger an agent by sending an email. Useful for support intake, structured request handling ("file an expense report from this receipt"), and routing inbound questions to a knowledge-base-grounded answer.

How it works​

You point a dedicated email address at ZenSearch (cloud customers get one out of the box; self-hosters wire their own — see below). Each inbound email is routed to the automations whose address and subject patterns match, and the agent runs against the email's body and metadata.

Common patterns:

Configuring an automation​

In the dashboard, create an automation and pick Email as the trigger. You'll be asked for:

FieldDescription
Address patternWhich inbound address triggers this automation. Supports a single * wildcard (e.g., support+*@yourcompany.com).
Subject patternOptional case-insensitive substring match on the subject line.
DeliveryWhere the agent's result goes — webhook, Slack, or email reply.

Multiple automations can match the same address; each runs once per delivered email.

Inbound delivery​

Cloud customers get a managed inbound address — copy it from the automation page and use it directly. Self-hosters have three supported routes:

1. Hosted email-receiving providers​

If your domain already routes mail through Postmark, SendGrid, or Amazon SES, point the provider's inbound webhook at ZenSearch. Each provider's webhook is authenticated with a secret you configure once. DKIM and SPF verdicts from the provider envelope are checked fail-closed — failing messages are dropped without invoking the agent.

2. Cloudflare Email Routing​

If your domain is on Cloudflare, the included sample Worker re-packages incoming mail and forwards it to ZenSearch using the Postmark format. No mail server required.

3. IMAP polling (air-gapped / self-hosted)​

For deployments that can't expose an HTTP endpoint or accept inbound MX, ZenSearch ships an in-process IMAP poll loop. Add an IMAP mailbox in the dashboard with the server, credentials (password or OAuth2 access token), and an optional poll interval. ZenSearch fetches unseen messages on each cycle and feeds them into the same automation pipeline as the webhook routes — dedup, routing, and thread resume all behave identically.

Two replicas can poll the same mailbox safely; an internal lock prevents duplicate processing.

Reply threading​

If a recipient replies to the agent's email response, ZenSearch matches the reply's In-Reply-To / References headers against any paused automation runs in the same thread. If a match is found, the reply is fed back into that run rather than starting a fresh one — so back-and-forth conversations work without losing context.

Limits and behavior​

  • Attachments: stripped at parse time. Attachment metadata (filename, size, MIME) is logged but contents are not currently ingested.
  • Body size: messages over the configured limit are rejected. The default is generous for normal correspondence.
  • Dedup: each Message-ID is processed once per team. Provider retries are absorbed silently.
  • DKIM / SPF: messages failing either check are dead-lettered without running an agent.
  • Failed deliveries: visible in the dashboard's automation runs view with the dropped reason.

Best practices​

  1. Use plus-addressing (support+billing@…, support+returns@…) to fan out a single mailbox into multiple automations.
  2. Add a subject-pattern filter for mailboxes that receive both human and bot mail — you don't want auto-replies kicking off agent runs.
  3. Test with shadow mode (see Shadow-mode automations) before wiring an automation to a customer-visible address.
  4. Set a delivery method on the automation; without one, the agent runs but the result has nowhere to go.