Auto-Route Invoices With Inbound Email Rules

Nylas introduced inbound email rules for Agent Accounts, enabling automatic invoice routing by matching sender fields and assigning messages to folders before application code runs. The rules support up to 50 conditions and 20 actions, and can reference domain lists for dynamic vendor management without redeployment.

A single inbound email rule can carry up to 50 match conditions and 20 actions — and it runs inside the mail infrastructure itself, before your webhook handler, your queue, or any line of your application code gets involved. That changes how you build something like invoice routing. The usual approach is: receive message.created , fetch the message, check the sender, call the folders endpoint to move it. Four network hops and a handler you have to deploy and monitor. With Agent Accounts https://developer.nylas.com/docs/v3/agent-accounts/ — programmatic mailboxes currently in beta — there's a declarative alternative: Rules that match sender fields and run assign to folder so invoices are already sitting in the finance folder when your application first sees them. The Policies, Rules, and Lists docs https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ define a chain: block , mark as spam , assign to folder , mark as read , mark as starred , archive , or trash .None of them attach to an individual mailbox. Instead, a workspace carries one policy id plus an array of rule ids , and every agent mailbox in that workspace inherits the lot. Each application gets a default workspace that holds any account you haven't placed elsewhere — attach your rules there once and every unassigned mailbox picks them up. All of this is optional, too: with no workspace policy attached, an account simply runs at your billing plan's maximum limits and delivers every inbound message straight to the inbox. Say invoices arrive from a handful of vendors. One rule, OR'd conditions, two actions: curl --request POST \ --url "https://api.us.nylas.com/v3/rules" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "name": "Invoices → Finance folder", "trigger": "inbound", "match": { "operator": "any", "conditions": { "field": "from.domain", "operator": "is", "value": "billing.vendor-a.com" }, { "field": "from.address", "operator": "contains", "value": "invoice@" } }, "actions": { "type": "assign to folder", "value": "<FINANCE FOLDER ID " }, { "type": "mark as read" } }' A rule does nothing until a workspace references it — add its ID to the workspace's rule ids array and it's live for every account there. Inbound rules can match from.address , from.domain , and from.tld with the operators is , is not , contains , and in list . Matching is case-insensitive. Hardcoding domains in rule conditions works until accounting onboards a new vendor and files a ticket. A domain -typed List fixes that. Create it, load it, and point the rule at it: 1. Create the list type is immutable after creation curl --request POST \ --url "https://api.us.nylas.com/v3/lists" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "name": "Invoice vendors", "type": "domain" }' 2. Add vendor domains — up to 1,000 items per request curl --request POST \ --url "https://api.us.nylas.com/v3/lists/<LIST ID /items" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "items": "billing.vendor-a.com", "invoices.vendor-b.io" }' Then the rule condition becomes: { "field": "from.domain", "operator": "in list", "value": "<LIST ID " } Now whoever maintains the vendor roster updates the List without touching the rule or redeploying anything — every rule that references the list picks up new values immediately. Values get lowercased, trimmed, and validated against the list type on write a domain list rejects full email addresses , and duplicates are silently ignored. Lists come in three types — domain , tld , and address — and the type decides which rule fields they can match. One caution: deleting a list cascades to its items, and any rule matching it through in list silently stops matching those values. Rules have fixed limits, and requests that exceed them are rejected with a validation error: | Cap | Value | |---|---| | Conditions per rule | 50 | | Actions per rule | 20 | Lists per in list condition | 10 | Characters per condition value | 500 | Fifty conditions sounds like a lot until you start inlining vendor addresses one condition at a time — which is exactly why the List pattern above exists. Ten lists per in list condition, each holding thousands of entries, scales much further than inline values ever will. Inbound rules match exactly three fields: from.address , from.domain , and from.tld . There's no subject matching, no body matching, no "has attachment" condition. So a rule can route mail from billing.vendor-a.com to the finance folder, but it can't catch "an invoice from an unknown sender." That split is actually a decent architecture: deterministic sender-based routing lives in the rule layer, and content-based classification — "is this PDF actually an invoice?" — stays in your application or LLM, working over a pre-sorted folder instead of a raw inbox. Two adjacent facts from the policy layer are relevant here too. Attachment limits size, count, and allowed MIME types on the workspace policy apply to inbound mail only — over-limit attachments are dropped from the stored message — so a policy with a 26214400-byte 25 MB attachment cap protects your invoice parser from absurd payloads before any code runs. And the same rule ids array also carries outbound rules, evaluated when the account sends; Nylas filters by trigger at evaluation time, so the two directions never cross-fire. Rules evaluate in priority order — lower runs first, the range is 0–1000, and the default is 10. The block action is terminal: for inbound mail it rejects at the SMTP stage, so a spam-block rule at priority 1 means junk never even reaches your invoice rule, let alone your LLM or your handler. The behavior worth knowing before an incident: rule evaluation fails closed . If a block rule can't be evaluated because of a transient infrastructure error — say a list lookup fails mid- in list match — the message gets blocked rather than waved through. Inbound SMTP responds with a 451 tempfail so the sending server retries instead of bouncing. The audit record carries blocked by evaluation error: true so you can tell an infrastructure hiccup apart from a genuine match. Every evaluation writes an audit entry. GET /v3/grants/{grant id}/rule-evaluations lists them newest-first, with the evaluation stage, the normalized sender data that was considered, the matched rule IDs, and the applied actions. When finance asks why a vendor's invoice vanished, that's a one-call answer instead of a log-diving session. Create one domain List with your top three vendors, one assign to folder rule referencing it, attach both to your default workspace, and send yourself a test invoice. Then check the rule-evaluations endpoint to watch the match happen. Total setup is three API calls. What's the most annoying piece of inbox sorting you're currently doing in application code?