Retention Policies: How Long Should an Agent Keep Mail?

Picture a typical story: an engineer spins up an OTP-extraction mailbox for the CI pipeline in the spring. It works, everyone forgets about it, and months later a security review finds the thing — an unattended inbox quietly accumulating verification emails, password-reset links, and signup confirmations for every test account the company has ever created. Nobody decided to build a credentials archive. It just happened, one retained message at a time.

That's the retention problem for agent mailboxes in a nutshell. A human cleans out an inbox occasionally, or at least owns the mess. An autonomous mailbox keeps whatever its retention settings say to keep, forever-ish, with no one looking.

What the defaults give you

On Nylas Agent Accounts (currently in beta), the free plan defaults are 30 days of inbox retention and 7 days for spam, with 3 GB of storage per organization. Both retention values are configurable through a policy — the admin-scoped resource that bundles limits and spam settings and applies to every account in a workspace.

Like all policy limits, the retention fields are optional: omit them and they default to your plan's maximum, and requesting a value above the plan maximum returns an error. So the dial only turns one way — toward keeping less — which is exactly the direction a privacy review wants it turned.

curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Short-lived agent policy",
    "limits": {
      "limit_inbox_retention_period": 365,
      "limit_spam_retention_period": 30
    }
  }'

One constraint to respect: limit_spam_retention_period must be shorter than limit_inbox_retention_period, so junk clears out ahead of the inbox. Attach the policy to a workspace (set its policy_id), and every agent grant in that workspace inherits it — including, if you attach it to your application's default workspace, every account you never explicitly placed anywhere.

The case for keeping less

Security teams have a phrase for stored data you don't need: attack surface with no upside. For agent mailboxes the calculus is unusually clean, because most agents are consumers of email, not archivists:

• An OTP or signup agent needs a message for the seconds it takes to extract a code. Anything past a day or two is pure liability — those messages are literally a pile of authentication material.
• A webhook-driven triage agent processes each message when message.created fires, then acts on its own systems. The mailbox copy is a cache, not a record.
• A CI testing mailbox needs messages for the duration of a pipeline run. Retention measured in days is generous.

Shorter retention also has a quota dividend: storage on the free plan is shared across the organization, so a fleet of chatty agents with long retention eats the 3 GB pool for everyone. Expiry is your garbage collector.

Two levers besides the clock

Retention decides how long a stored message lives. Two adjacent controls decide what gets stored in the first place, and they're worth setting in the same policy review.

First, inbound rules. A block rule rejects mail at the SMTP layer, so the message is never stored at all — retention zero, enforced before delivery. One step softer, a mark_as_spam rule routes matched mail to the junk folder, and junk lives on the spam retention clock, not the inbox one. On free-plan defaults that's 7 days instead of 30. A rule that marks newsletter domains or known-noisy senders as spam is effectively a shorter retention period for noise, without touching the policy that governs real mail:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Noise gets the short clock",
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "in_list", "value": ["<NOISY_DOMAINS_LIST_ID>"] }
      ]
    },
    "actions": [{ "type": "mark_as_spam" }]
  }'

Second, attachment limits. The same policy carries limit_attachment_size_limit, limit_attachment_count_limit, and limit_attachment_allowed_types. Attachments that exceed those caps are dropped from the stored message — the message itself still arrives and message.created still fires — which means the bulkiest, most breach-interesting payloads never enter your storage pool. For an OTP inbox that only ever needs message bodies, a tight attachment policy is retention's natural companion: less stored per message, and each message stored for less time.

One caveat if you lean hard into "the mailbox is just a cache": webhook payloads for bodies over roughly 1 MB arrive as message.created.truncated with the body omitted, so your processing path must fetch the full message by ID — and that fetch has to happen while the message still exists. Aggressive retention plus a queue that can lag for days is a quiet data-loss bug.

The case for keeping more

It's not one-sided, and pretending otherwise produces bad policies. Two agent categories genuinely benefit from long retention:

• Conversational agents that handle multi-day threads reconstruct context by fetching thread history. Aggressive expiry amputates the agent's memory mid-conversation — a support thread that resumes after three weeks needs the earlier messages to still exist.
• Agents whose mail is the audit trail. The sent folder is a complete record of every action an outbound agent took. If your compliance story leans on "we can review everything the agent sent," your retention period is your audit window.

The resolution is to stop looking for one number. Workspaces make retention per-archetype: an ephemeral-jobs workspace with short retention for OTP and testing agents, a conversational workspace with long retention for support agents, each carrying its own policy. The docs recommend separate workspaces per agent archetype for exactly this kind of divergence.

Retention is the cleanup you don't have to build

The alternative to platform-level retention is application-level cleanup: cron jobs that list old messages and delete them, with all the usual failure modes — the job silently breaking, the new mailbox someone forgot to enroll, the deletion script that needs its own permissions and monitoring. A policy attached to the default workspace has none of those problems. New agents inherit it the moment they're created, and there's no job to break.

That's the real argument for configuring this on day one rather than after the security review: retention set by policy is a property of the system, not a behavior of your code.

A 15-minute exercise for this week: list your agent mailboxes, write down what each one actually does with a message after processing it, and ask what the oldest message in each inbox is doing for you. If the answer is "nothing," set the retention period to match the job — the policies guide and the mailboxes overview cover everything you need. How long does your longest-lived agent conversation actually run?