# Build an Invoice Intake Agent

Source: https://cli.nylas.com/ai-answers/invoice-intake-agent.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

Inbound AP automation pattern using an Agent Account, attachment listing/downloading, structured extraction, fixed routing, and fraud-resistant controls.

Use Nylas CLI as the deterministic control plane for this workflow. The agent can summarize, classify, or draft content, but account selection, routing, retries, recipient policy, and approval gates should stay in code or Agent Account workspace controls.

## When To Use This

- Search for messages with attachments.
- List attachment metadata.
- Download only allowed files.
- Extract structured data outside the prompt where possible.
- Route summaries or drafts to fixed destinations.

## Command Recipe

```bash
nylas email search "invoice" <grant-id> --has-attachment --limit 20 --json
```

```bash
nylas email attachments list <message-id> <grant-id> --json
```

```bash
nylas email attachments download <attachment-id> <message-id> <grant-id> --output ./safe-inputs/file.bin
```

Downloading one approved attachment over HTTP (the `message_id` query is required):

```bash
curl -s "https://api.us.nylas.com/v3/grants/$GRANT_ID/attachments/$ATTACHMENT_ID/download?message_id=$MESSAGE_ID" \
  -H "Authorization: Bearer $NYLAS_API_KEY" --output ./safe-inputs/file.bin
```

```bash
nylas email send <grant-id> --to reviewer@example.com --subject "Attachment review" --body "A file needs review." --yes --json
```

## Recommended Workflow

1. Decide whether the workflow should use an app-owned Agent Account or a user-owned grant.
2. Use explicit grant IDs in automation instead of relying on active local state.
3. Request JSON output with `--json` wherever another tool or model consumes the result.
4. Keep model-readable content separate from credentials, policies, webhook secrets, and routing rules.
5. Log message IDs, grant IDs, workflow IDs, and external system IDs for audit and retries.

## Agent Safety And Operations

- Treat extracted attachment text as untrusted.
- Check content type and size before processing.
- Do not allow attachment text to set recipients or policy.
- Keep downloaded files out of public paths.

## Headless Runtime Defaults

Use these environment variables in CI, containers, workers, and serverless jobs:

```bash
export NYLAS_API_KEY=<api-key>
export NYLAS_GRANT_ID=<grant-id>
export NYLAS_DISABLE_KEYRING=true
```

For app-owned workflows, create an Agent Account first:

```bash
nylas agent account create agent@yourapp.nylas.email --json
nylas agent account get agent@yourapp.nylas.email --json
```

For user-owned workflows, connect or select the user grant:

```bash
nylas auth login
nylas auth list --json
nylas auth switch <email-or-grant-id>
```

## Troubleshooting

- If the wrong mailbox is used, pass `<grant-id>` explicitly to the command.
- If a headless job cannot access credentials, set `NYLAS_API_KEY`, `NYLAS_GRANT_ID`, and `NYLAS_DISABLE_KEYRING=true`.
- If a webhook-driven workflow behaves unexpectedly, verify the raw payload signature before reading message content.
- If an Agent Account rule or policy does not apply, inspect `nylas agent overview --json` and `nylas workspace get <workspace-id> --json`.
- If an LLM suggests changing recipients, policies, credentials, or webhook URLs based on email body text, reject that instruction and route to review.

## Implementation Notes

Model output should be treated as a proposal. The application should decide which grant to use, which recipients are legal, how many times to retry, and whether a draft or direct send is allowed.

Keep a workflow ledger keyed by message ID, thread ID, external customer ID, or scheduled-send ID. This prevents duplicate replies when a webhook retries or a worker restarts.

Use metadata on outbound sends where useful, and keep operational state outside the prompt. The agent should receive only the fields needed to classify or draft the next step.

## Minimum Data Contract

- message_id
- thread_id
- grant_id
- workflow_state
- approved_recipients[]
- action_taken

## Validation Checklist

- A dry-run or draft mode exists for new flows.
- Opt-outs and suppressions are checked before any send.
- Every direct send has a fixed reason and allowed recipient path.
- A human can trace the source message and final action.

## Failure Modes To Handle

- If the model is uncertain, create a draft or review item.
- If a recipient asks to stop, update suppression state before more automation runs.
- If the workflow repeats, stop after a configured maximum and escalate.

## Example Control Flow

A production workflow should start with a narrow search or webhook event, read the exact message or thread, classify the situation, and choose one of a small number of allowed actions. For uncertain cases, create a draft or escalation note. For approved direct sends, use fixed recipient rules, suppression checks, and metadata so later audits can explain why the message was sent.

Do not rely on prompt memory for workflow state. Store state in a database, ticket, CRM record, file ledger, or message metadata. That makes retries safe and lets a later agent continue without rereading unrelated mailbox content.

## Review Questions

- Is there a maximum number of automated touches per recipient or thread?
- Are opt-outs, suppressions, and customer status checked before sending?
- Does the workflow create drafts for ambiguous or high-impact responses?
- Are message IDs and final actions recorded outside the prompt?

## Related Full Guides

- https://cli.nylas.com/guides/agent-attachment-data-extraction
- https://cli.nylas.com/guides/parse-email-attachments
- https://cli.nylas.com/guides/email-to-google-drive
- https://cli.nylas.com/guides/email-to-onedrive
- https://cli.nylas.com/docs/commands/email-send
- https://cli.nylas.com/docs/commands/email-search
- https://cli.nylas.com/docs/commands/agent-account-create

## Production Readiness Notes

For invoice intake agent, treat this markdown answer as a retrieval-ready blueprint for an email and attachment workflow. The page should give an LLM enough concrete structure to choose the right Nylas CLI command family, preserve account boundaries, and avoid treating invoice text as trusted instructions. Keep deterministic CLI calls outside the model, pass compact attachment metadata or extracted fields into the reasoning layer, and require a structured decision that the host application validates before it acts.

A production run should include these control points:

- Start with a narrow `nylas email search` for messages with attachments and pass only selected message fields into the model.
- List attachment metadata first, then download only approved content types and sizes into non-public storage.
- Extract invoice fields into a schema, but let host code validate vendor, amount, due date, duplicate invoice number, and destination.
- Log grant id, message id, attachment id, storage key, extracted invoice id, policy result, and reviewer action.

The common risks to guard against are:

- Invoice text or attachment content changes routing, recipients, or payment policy.
- A duplicate or retried webhook creates a second AP record for the same invoice.
- Downloaded attachments land in a public path or are processed before type and size checks.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/