Restricting Attachments in Agent Inboxes

Three fields on a policy decide which attachments ever reach your email agent:

{
  "name": "Locked-down agent inbox",
  "limits": {
    "limit_attachment_size_limit": 26214400,
    "limit_attachment_count_limit": 20,
    "limit_attachment_allowed_types": ["application/pdf", "image/png"]
  }
}

Size (that's 25 MB in bytes), count per message, and an allowlist of MIME types. POST that to /v3/policies, attach the resulting policy_id to a workspace, and every Agent Account in the workspace enforces it on inbound mail from then on.

Why an autonomous reader needs this more than you do

When a human gets a suspicious attachment, there's a judgment step: weird sender, weird filename, don't open it. An email agent has no such instinct unless you build one — and the agents most worth building are exactly the ones that process attachments: parsing invoices, extracting resumes, reading shipped documents. That processing step is the attack surface. A hostile PDF aimed at your parser, a 10,000-page document aimed at your token budget, a zip bomb aimed at your storage — all of them arrive the same way legitimate input does.

You can defend in application code, but then every consumer of the mailbox has to get it right, forever. Policy limits on Nylas Agent Accounts (a beta feature) enforce the constraint at the mailbox itself, before any of your code runs.

One clarification that saves a support ticket: inbound rules can't do this job. Rules match on sender fields — from.address, from.domain, from.tld — and know nothing about what a message carries. Attachment control lives on the policy, and only there.

From policy to enforced, end to end

The policy applies through a workspace, not directly to a grant. The full wiring is three calls. Create the policy at /v3/policies, set it as the workspace's policy_id (a PATCH /v3/workspaces/{workspace_id} if the workspace already exists), then create the account into that workspace:

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",
    "workspace_id": "<WORKSPACE_ID>",
    "settings": {
      "email": "[e-mail]"
    }
  }'

That's the same POST /v3/connect/custom endpoint used for other providers, with "provider": "nylas" and no OAuth tokens — the response hands back the grant_id you'll use everywhere else. Omit workspace_id and the account lands in your application's default workspace instead, which is also a feature: attach your locked-down policy to the default workspace and every account you forget to place explicitly inherits the strict limits, not the loose ones. Fail closed by default, loosen deliberately per workspace.

What actually happens to an over-limit attachment

This is the behavior worth understanding precisely, because it's not what most people guess. The message is not bounced. Attachments that exceed the policy caps are dropped from the stored message — the message itself is still delivered, and the message.created webhook still fires.

For an agent pipeline, that's the right call. The text of the message still arrives, so a triage agent can still classify it, reply to it, or escalate it. What's gone is the payload you decided your system shouldn't ingest. A bounce would leak your filtering policy to the sender and break legitimate conversations that happen to carry an oversized file; a silent drop keeps the conversation alive while protecting the processor.

The flip side: if your agent expects attachments — an invoice-processing inbox, say — set the limits with the real workload in mind, because a dropped attachment doesn't announce itself in the message body. Size the cap from your largest legitimate document, not from a default.

Inbound only — the sent side is sacred

Attachment limits apply to inbound mail exclusively. They're never applied to the stored sent copy, so anything your agent sends keeps all of its attachments in the sent folder. That asymmetry is deliberate: the sent folder doubles as the audit record of what the agent actually transmitted, and an audit record with policy-stripped attachments would be lying to you.

Outbound has its own ceiling, enforced separately: 40 MB total message size on every outbound path — API sends, draft sends, and SMTP submission. (Recipient servers often enforce lower limits, typically around 25 MB, so staying under the cap doesn't guarantee acceptance at the remote end.)

The read path for whatever survives

Attachments that pass policy show up as IDs on the message object, and your agent downloads them through the standard endpoint — the quickstart shows the full receive flow:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Because the policy already filtered by size, count, and type, the code behind this call gets to make simpler assumptions: nothing here is 200 MB, nothing is an executable, nothing arrives in batches of 80. Your parser still shouldn't trust the content — a 25 MB PDF can still be malformed — but you've shrunk the input space it has to survive.

Choosing values per agent archetype

Like every policy limit, all three fields are optional — omit one and it defaults to your plan's maximum, and values above the plan maximum are rejected. The useful exercise is matching the allowlist to the job:

• Invoice processor: application/pdf only, generous size, low count.
• Resume intake: PDF plus the document formats you genuinely parse — every extra type is another parser you're promising to secure.
• OTP/notification inbox: arguably no attachments at all; codes live in message bodies.
• General support triage: wider types, but a tight size cap, since the agent reads rather than processes.

Different jobs mean different policies, and workspaces let each agent group carry its own — the Policies, Rules, and Lists guide covers attachment limits alongside the spam and retention settings that share the same policy object.

Two follow-up questions that come up immediately:

Can I tighten limits after accounts exist? Yes — swap the workspace's policy_id with a PATCH /v3/workspaces/{workspace_id} and every account in the workspace picks up the new limits. No per-account migration, no grant updates.

Do the limits strip attachments from drafts my agent sends? No. The inbound-only behavior covers this: sent copies always keep all of their attachments, whether the send came from /messages/send, a draft, or SMTP submission. The only outbound constraint is the 40 MB total message cap.

Next step: write down every MIME type your agent's processing code can genuinely handle today. That list — not your plan's maximum — is your limit_attachment_allowed_types, and anything beyond it is risk you're carrying for no benefit.