Audit-log every email your AI agent sends

Nylas engineer details an architecture for audit-logging every email an AI agent sends, emphasizing that the live mailbox is not an audit trail. The design uses a separate immutable store, capturing outbound message IDs and inbound webhooks to create a defensible record. The post provides CLI commands for provisioning an Agent Account and outlines the pattern for building a write-once-read-many audit log.

When an autonomous agent gets an email address of its own, the first question your security team asks isn't "can it send mail?" It's "can you prove, six months from now, exactly what it said and to whom?" That's a different problem from "does it work." A demo that fires off a few support replies looks great in a sprint review. But the moment a real customer says "your bot promised me a refund," or a regulator asks for the complete record of what an automated system told a data subject, you need a defensible trail — an immutable record of every outbound and inbound message the agent touched, captured outside the mailbox the agent can also delete from. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. But the architectural point here is provider-agnostic and it's the part most "AI email" tutorials skip: the live mailbox is not your audit log. It's mutable, it has retention limits, and the same agent that sends mail can also trash it. If your only record of what the agent did lives in the inbox, you don't have an audit trail — you have a working copy. There are two stores in this design, and keeping them separate is the whole point. message id and thread id . Nothing in it is ever updated or deleted in normal operation. This is the record you hand a reviewer.The audit store is the thing you build. Nylas gives you the two capture points — the send response and the inbound webhook — but the immutability is your responsibility. That means a WORM write-once-read-many object store, an append-only table with no UPDATE / DELETE grant for the app role, or a hash-chained log where each entry commits to the hash of the previous one so tampering is detectable. Pick whichever your compliance posture demands; the capture pattern below is the same regardless. One thing I want to be honest about up front: custom metadata is not supported on Agent Accounts. On a normal connected grant you might be tempted to stamp an audit ID into message metadata and filter on it later. That door is closed here, and it's the wrong door anyway — metadata lives in the same mutable mailbox you're trying to audit If you've used any grant-scoped Nylas endpoint, there's nothing new on the data plane. An Agent Account is just a grant with a grant id . It addresses the same /v3/grants/{grant id}/ routes as any other grant — Messages, Threads, Folders, Attachments, the lot. Same auth header, same payloads. The audit subsystem hangs off two of those routes plus one app-level webhook. So the spine of this post is small: message id and thread id plus the payload. message.created webhook, fetch the full message and record it. thread id .That's it. Everything else is plumbing around making the store immutable. You need a registered domain a custom domain, or a Nylas .nylas.email trial subdomain and an Agent Account on it. New domains warm over roughly four weeks before they're at full sending reputation, so provision early. Provision via the API with POST /v3/connect/custom : curl --request POST \ --url 'https://api.us.nylas.com/v3/connect/custom' \ --header 'Authorization: Bearer <NYLAS API KEY ' \ --header 'Content-Type: application/json' \ --data '{ "provider": "nylas", "settings": { "email": "support@yourcompany.com" }, "name": "Support Bot" }' The response carries the grant id as data.id the body is {"data": {"id": "<grant id ", ...}} — hold onto it; every audit capture is scoped to it. There's no refresh token to manage; an Agent Account has no OAuth flow to expire. Or, the CLI line I actually type: nylas agent account create support@yourcompany.com --name 'Support Bot' The API auto-creates a default workspace and policy. If you want a custom policy governing send limits or spam rules later, attach it with nylas workspace update <workspace-id --policy-id <policy-id — there's no --workspace flag on create. :::info New to Agent Accounts? Start with the Agent Accounts overview https://developer.nylas.com/docs/v3/agent-accounts/ and the supported-endpoints reference https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/ , which lists every route a grant exposes. ::: This is the easy half, and the half people forget. When you send, the API hands back the created message — including its id and thread id . That response is your audit record for the outbound side. Capture it synchronously, in the same code path that does the send, before you return success to the caller. Don't rely on reading it back from the mailbox later; the mailbox is mutable. Send with the API: curl --request POST \ --url 'https://api.us.nylas.com/v3/grants/<GRANT ID /messages/send' \ --header 'Authorization: Bearer <NYLAS API KEY ' \ --header 'Content-Type: application/json' \ --data '{ "to": { "email": "customer@example.com" } , "subject": "Re: your refund request", "body": "Hi — your refund of $40 has been approved and will post in 3-5 days." }' The 200 response includes data.id the message id and data.thread id . Write a record like this to your append-only store the instant you get it: { "direction": "outbound", "message id": "<from data.id ", "thread id": "<from data.thread id ", "grant id": "<GRANT ID ", "to": "customer@example.com" , "subject": "Re: your refund request", "body sha256": "<hash of the body you sent ", "body": "Hi — your refund of $40 has been approved...", "captured at": "<RFC3339 timestamp at write time " } Storing a body sha256 alongside the body is cheap insurance: it's the per-record commitment you chain together if you want tamper-evidence across the whole log. The CLI equivalent, with --json so you can pipe the response straight into your capture step: nylas email send support@yourcompany.com \ --to customer@example.com \ --subject "Re: your refund request" \ --body "Hi — your refund of \$40 has been approved and will post in 3-5 days." \ --json When the agent replies inside an existing conversation, send with reply to message id so the new message keeps the same thread id . That thread continuity is what lets you reconstruct a full back-and-forth from the audit store later: curl --request POST \ --url 'https://api.us.nylas.com/v3/grants/<GRANT ID /messages/send' \ --header 'Authorization: Bearer <NYLAS API KEY ' \ --header 'Content-Type: application/json' \ --data '{ "to": { "email": "customer@example.com" } , "reply to message id": "<ORIGINAL MESSAGE ID ", "body": "Following up — the refund posted this morning." }' The CLI equivalent uses --reply-to : nylas email send support@yourcompany.com \ --to customer@example.com \ --reply-to <ORIGINAL MESSAGE ID \ --body "Following up — the refund posted this morning." \ --json A note on attachments, since auditors love asking about them: via the API you attach either Base64 strings in the JSON attachments array, or multipart where the file form field is named attachment not file . nylas email send has no attachment flag — if the agent needs to send files, build the message as a draft with nylas email drafts create --attach and send that. Either way, record the attachment metadata filename, size, content hash in your audit entry; you rarely want to copy the bytes themselves into the log. Inbound is where the separate-store discipline earns its keep, because inbound mail arrives in a mailbox the agent can later modify or that retention can age out from under you. The capture point is the message.created webhook. Two facts about Nylas webhooks shape how you wire this up, and getting them right is the difference between a clean audit log and a flaky one: Webhooks are application-scoped, not grant-scoped. You subscribe once, at the app level, and every grant's events land at that one endpoint. Each payload carries a grant id you filter on. So you don't create a webhook per Agent Account — you create one and route by grant id . Subscribe with the API: curl --request POST \ --url 'https://api.us.nylas.com/v3/webhooks' \ --header 'Authorization: Bearer <NYLAS API KEY ' \ --header 'Content-Type: application/json' \ --data '{ "trigger types": "message.created" , "webhook url": "https://yourapp.com/hooks/nylas", "description": "Agent Account audit capture" }' Or with the CLI: nylas webhook create \ --url https://yourapp.com/hooks/nylas \ --triggers message.created \ --description "Agent Account audit capture" For local development you can run a receiver with nylas webhook server --tunnel cloudflared --secret <your-webhook-secret , which verifies signatures on the way in and prints each event — handy for confirming your capture logic before you point it at production. Here's the rule that keeps you out of trouble: don't rely on the webhook payload for the message body — fetch the full message when you need it. The Nylas docs are a little inconsistent on whether the body ships inline the general webhook doc says it's inline unless the message exceeds ~1 MB, at which point the trigger becomes message.created.truncated and the body is omitted; the agent-accounts reference leans toward summary fields . Both agree on the action , so do that: message.created , read the data.object.id the message id and grant id . message.created.truncated , the body was dropped, so you must re-fetch. curl --request GET \ --url 'https://api.us.nylas.com/v3/grants/<GRANT ID /messages/<MESSAGE ID ' \ --header 'Authorization: Bearer <NYLAS API KEY ' The CLI equivalent: nylas email read <MESSAGE ID support@yourcompany.com --json Fetching by id gives you one source of truth for the body — the full message — instead of trying to reconcile an inline payload against a truncated one. For an audit log you want exactly one canonical version of each message, and this is how you get it. Nylas guarantees at-least-once delivery: the same event can arrive up to three times. For an append-only store, that's a real hazard — naive code would write the same inbound message three times and your "immutable" log now has duplicates. Dedup on the top-level notification id . That id is constant across all retries of one event, so it's the correct delivery-dedup key. Keep a set of processed notification ids a unique constraint in the DB, or a short-TTL cache and drop any you've already seen. As a second guard, you can also key on the inner data.object.id the message id so you never act twice on the same message even across distinct events. Both together give you exactly-once semantics on top of at-least-once delivery.And verify the signature before you process anything. Nylas signs each webhook with X-Nylas-Signature — a hex HMAC-SHA256 of the raw request body using your webhook secret. Recompute it over the raw bytes not a re-serialized JSON object and compare in constant time. If you use Node's crypto.timingSafeEqual , guard that both buffers are the same length first, because it throws on a length mismatch. The CLI can check a captured payload for you: nylas webhook verify \ --payload-file ./captured-body.json \ --signature <X-Nylas-Signature value \ --secret <your-webhook-secret Log the verification result , not the secret, as part of each audit entry — a reviewer wants to see that every recorded inbound event was authenticated. When an incident lands, you read from your audit store, not the mailbox. Group your records by thread id and you have the complete conversation — every inbound message and every outbound reply the agent produced, in order, with the body you captured at the time and the hash that proves it hasn't changed since. You can cross-check against the live mailbox while the messages are still inside the retention window — GET /v3/grants/<GRANT ID /messages?thread id=<THREAD ID or nylas email list support@yourcompany.com --json — but treat that as a convenience, not the record. Past the retention window, or after the agent has trashed something, the mailbox can't answer the question. Your append-only store can. That's the entire reason it exists. "Delete" in the mailbox isn't permanent — and that's fine, because your audit store is the record anyway. DELETE /v3/grants/{id}/messages/{id} moves a message to Trash unless you pass ?hard delete=true . The CLI nylas email delete only trashes. Thread deletion only trashes and has no hard-delete option at all. The only true wipe is deleting the grant itself DELETE /v3/grants/{id} / nylas agent account delete . None of that touches your separate audit log, which is exactly the separation you want: erasure in the live mailbox and retention in the audit store are two independent decisions. Capture sends synchronously; capture inbound idempotently. The send response is one-shot — if you don't record it in the send path, it's gone. The inbound webhook is at-least-once — record it idempotently or you'll get duplicates. Different failure modes, different handling. Don't audit-log secrets. Record message metadata, bodies you're entitled to retain, hashes, timestamps, and verification results. Never write the webhook secret or the API key into the store. The point of the log is to prove what the agent communicated, not to become a second place your credentials leak from. nylas agent account , nylas email , and nylas webhook in full.Build the two capture points, make the store append-only, and you can answer the question that actually matters when an agent has its own inbox: not "did it send mail," but "here is exactly what it said, to whom, and when — and here's the proof it hasn't changed." When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com :