GDPR retention and erasure for an agent mailbox

Nylas developer tools enable GDPR-compliant retention and erasure for AI agent mailboxes. The platform provides API endpoints to set retention periods and hard-delete messages, ensuring personal data is not stored indefinitely. A step-by-step walkthrough demonstrates how to configure these features using curl commands or the Nylas CLI.

Most "AI email" demos never think about deletion. The agent reads, replies, files things away, and the inbox just grows. That's fine in a demo. It is a problem the first time a real person emails your agent, because the moment that mailbox holds someone else's name, address, order history, or support complaint, you've taken on a data-protection obligation — and "we kept everything forever" is not a defensible retention policy. An Agent Account on Nylas accumulates personal data you have to be able to purge. It's a mailbox the agent owns — support@yourcompany.com answering to a model instead of a human — and every inbound message lands in it. Under GDPR that data needs two things you can prove: a retention window so it doesn't live forever, and an erasure path so you can delete a specific person's mail when they ask. This post builds both, with the curl and the CLI for each step. A quick, honest caveat before any of it: this is a docs-and-demo walkthrough, not legal advice. The Nylas primitives below cover the mail held in the mailbox . Any derived copy you made — rows in your own database, lines in your application logs, a vector store you embedded the message into — is yours to purge separately. The API can delete the message; it can't reach into your Postgres. Keep that in mind throughout. Nothing new to learn on the data plane. An Agent Account is just a grant with a grant id , so everything you already know about Messages and Threads applies directly — listing, reading, and deleting mail run against the same grant-scoped endpoints any other Nylas integration uses. Retention and erasure split cleanly into two layers: limit inbox retention period and limit spam retention period . Set them once and Nylas deletes aged-out mail for you, per account, with no cron job on your side. GET /v3/grants/{grant id}/messages filtered by sender, then hard-delete each one with DELETE .../messages/{id}?hard delete=true — a plain delete only trashes the message, which isn't erasure. For a full identity wipe, you delete the grant itself.The split matters because the two answer different questions. Retention answers "how long do we keep anything?" — a blanket time bound. Erasure answers "delete this person's data, now" — a targeted request. A compliant agent mailbox needs both; one doesn't substitute for the other. I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for. Where it matters I'll show the curl and the nylas ... form side by side, because in practice you set retention once through the API and run erasure ad hoc from a terminal when a request comes in. You need an Agent Account, an API key for the same application, and the host set to https://api.us.nylas.com . Every API call below carries Authorization: Bearer <NYLAS API KEY . If you don't have an account yet, you provision one against a registered domain — either the API: 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 Agent" }' or the CLI, which creates the nylas connector for you if it doesn't exist yet: nylas agent account create support@yourcompany.com --name "Support Agent" Either path returns a grant id . The API also auto-creates a default workspace and a default policy for the account — that default workspace is where you'll attach the retention policy in a moment. Full background lives in the Agent Accounts docs https://developer.nylas.com/docs/v3/agent-accounts/ and the Policies, Rules, and Lists guide https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ . CLI reference is at cli.nylas.com/docs/commands https://cli.nylas.com/docs/commands . One plan note up front: on the free plan, retention defaults to 30 days in the inbox and 7 days in spam , and those defaults aren't configurable. The two retention fields below are configurable on paid plans, where you set your own windows. So if you're prototyping on the free tier, you already have a 30-day inbox bound whether you ask for it or not — which is a reasonable default, but probably not the number your legal team picked. Retention is two fields inside a policy's limits object: limit inbox retention period — days a message stays in the inbox before Nylas deletes it. limit spam retention period — days a message stays in spam before deletion. This Both take a number of days. Pick windows that match your documented retention schedule — the number you'd write down for an auditor, not a number you guessed. Here's a policy that keeps inbox mail for a year and spam for 30 days: curl --request POST \ --url "https://api.us.nylas.com/v3/policies" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "name": "Support Agent Retention Policy", "limits": { "limit inbox retention period": 365, "limit spam retention period": 30 } }' The CLI takes the same JSON body through --data , so the policy you describe is identical: nylas agent policy create --data '{ "name": "Support Agent Retention Policy", "limits": { "limit inbox retention period": 365, "limit spam retention period": 30 } }' Both return a policy id . Hold onto it — a policy does nothing on its own. It only takes effect once a workspace points at it, and every Agent Account in that workspace inherits the windows. You attach it to the default workspace your account already landed in: curl --request PATCH \ --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE ID " \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "policy id": "<POLICY ID " }' nylas workspace update <WORKSPACE ID --policy-id <POLICY ID That's the entire retention story on the platform side. From here, Nylas enforces the windows itself — there's no scheduled job for you to write, monitor, or page on when it silently stops running at 3am. The part I like as an SRE is exactly that: retention isn't a script that can rot. It's a property of the account, declared once, enforced by the platform. A workspace with no policy attached runs its accounts at your plan's maximum limits — which on a paid plan can mean no retention bound at all. So "we have an Agent Account" does not imply "we have a retention window." Attaching the policy is the step that makes the claim true. If you ever need to widen or tighten the window, PATCH the policy and every account in the workspace follows; on the default workspace, policy id and rule ids are the only fields you're allowed to change, which keeps this hard to get wrong. Retention handles the passive case — mail aging out on a schedule. Erasure handles the active one: a named individual exercises their right to be forgotten and you have to remove their mail specifically, today, regardless of how old it is. The shape is two steps. First, find every message from that person. Then delete each one. Both run against the grant, on the same Messages endpoints any Nylas app uses — there's nothing Agent-Account-specific here, which is the point. Filter the message list by sender. The Messages API takes a from query parameter that matches the sender address, so a single call returns the candidate set: curl --request GET \ --url "https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID /messages?from=jane.doe@example.com&limit=50" \ --header "Authorization: Bearer <NYLAS API KEY " The CLI exposes the same filter as --from , and --id prints the message IDs you'll feed into the delete step: nylas email list <NYLAS GRANT ID --from jane.doe@example.com --id A few honest things to watch for, because "find their messages" is deceptively simple. --from matches the sender , so this finds mail the subject sent to the agent. Mail the agent sent to the subject lives in the Sent folder with the agent as sender — pass --folder SENT or list all folders and filter on the recipient side if your erasure scope includes outbound copies. And one person can email from more than one address; if you only have a name, you may need to run the lookup for each known address. Don't assume a single from value captures everything tied to a person. This is the step where the obvious call does the wrong thing, and it matters more here than anywhere else in the post. A plain DELETE on a message does not erase it — it moves the message to Trash . For a right-to-erasure request, trashed mail is still retained mail, and "we moved it to a folder" is not deletion. To actually remove a message, you pass ?hard delete=true , which deletes it immediately instead of trashing it, and that operation is irreversible: curl --request DELETE \ --url "https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID /messages/<MESSAGE ID ?hard delete=true" \ --header "Authorization: Bearer <NYLAS API KEY " Two things gate that flag. First, hard delete has to be enabled for your application — turn on Enable hard delete in the Nylas Dashboard https://dashboard-v3.nylas.com/ under Customizations API before the parameter does anything. Second, and this is the one to internalize: the CLI cannot hard-delete. nylas email delete only moves a message to Trash — there is no hard-delete flag on it. So for true erasure of an individual message, the API is your only path: CLI: trashes the message — does NOT permanently erase it nylas email delete <MESSAGE ID <NYLAS GRANT ID That's fine for an inbox-cleanup workflow, but don't reach for it to satisfy an erasure request and assume the data is gone — it's sitting in Trash. Threads have the same trap, with no escape hatch. Deleting a thread DELETE /v3/grants/{grant id}/threads/{thread id} , or nylas email threads delete moves the thread and all its messages to Trash. There is no hard delete parameter on the thread endpoint at all — so thread deletion is a convenience for clearing a conversation out of view, not an erasure primitive. If a single back-and-forth carried the personal data across several replies, list the thread's messages and hard-delete each one individually; don't rely on the thread delete to erase them. So the erasure loop is: list by sender, collect the message IDs, then DELETE .../messages/{id}?hard delete=true on each, through the API. Keep an audit record of what you deleted and when — the message IDs and a timestamp — without storing the message content you just erased. A proof-of-erasure log that quietly retains the bodies defeats the entire exercise; log the fact of deletion, not the data. Sometimes the subject is the agent identity. If the personal data tied to one person is the entire reason an Agent Account exists — a per-customer agent mailbox, say, that you spun up for a single client who's now offboarding — hard-deleting individual messages is the long way around, and it's also the one case where the CLI gives you a clean full wipe. Deleting the grant removes the whole mailbox: every message, thread, folder, and the connection itself. This is the only full-erasure path that doesn't depend on the hard delete toggle, because it tears down the mailbox rather than emptying it message by message. curl --request DELETE \ --url "https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID " \ --header "Authorization: Bearer <NYLAS API KEY " The CLI does this through the agent-account or auth commands — both revoke the same underlying grant: nylas agent account delete support@yourcompany.com --yes nylas auth revoke <NYLAS GRANT ID This is the nuclear option, and it's the right one for full erasure of an agent identity. It's also irreversible — the grant and its mailbox are gone, with no undelete. Reach for per-message hard-delete when you're scrubbing one person out of a shared agent mailbox, and grant deletion when the entire mailbox represents the person you're erasing. A few things the demo glosses over that a compliance review won't: Custom metadata isn't available on Agent Accounts. On a normal grant you might tag messages with a subject ID in metadata to make erasure lookups trivial. That's not an option here — Agent Accounts don't support custom metadata — so your erasure index has to live in your system, keyed off the message IDs you already store. Plan for that when you design the handler. Derived copies are your problem, not the API's. This is worth repeating because it's the most common gap. If your agent summarized a thread into your database, embedded a message into a vector store, or wrote the sender address into a log line, deleting the message from the mailbox leaves all of those untouched. Erasure is only complete when every copy is gone. Build the deletion of your derived data into the same handler that calls the Nylas DELETE. Retention defaults aren't a policy you chose. The free-plan 30-day inbox / 7-day spam window is a default, not a decision. If you're on a paid plan and never attached a policy, your accounts run at plan maximums — potentially no bound at all. Don't mistake "it seems to clean up" for "we have a documented retention schedule." Attach the policy explicitly. limit spam retention period must be shorter than limit inbox retention period. It's a hard constraint the API enforces. Set both, and set spam lower. A plain delete is not erasure. This is the single most important thing to get right in this post. A bare DELETE on a message moves it to Trash; thread deletion trashes the whole conversation; the CLI's nylas email delete and nylas email threads delete only trash. None of those erase. Erasure requires either ?hard delete=true on the message endpoint API only, with the Dashboard toggle enabled or deleting the grant. Treat "I deleted it" and "I erased it" as different claims, because the platform does. Hard-delete and grant deletion are irreversible. Once you do erase — hard delete=true on a message, or DELETE on the grant — there's no undelete and no Trash to recover from. Confirm the subject and the ID set before an erasure pass. That's exactly what you want for a right-to-erasure request, and exactly what you don't want to trigger by accident. None of this is legal advice, and your retention windows and erasure SLAs should come from your own data-protection program, not from the example numbers above. What the platform gives you is the mechanism: a declarative retention bound that the platform enforces, and a deterministic deletion path you can run on demand. The policy layer matters most for compliance — it's the difference between intending to delete old data and proving the system does. nylas agent , nylas workspace , and nylas email command surface used throughout this postWhen this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com :