Skip to content
Skip to main content

How to give an AI agent read-only email access

Last updated:

Most email agents only need to read. A summarizer, a classifier, or a “what needs my attention today” agent never has to send a message or delete one. If that agent runs with a key that can send, one prompt injection in one inbound email is enough to make it send mail as your user.

This recipe creates a Nylas IAM key that can read one mailbox and nothing else. Send and delete requests fail with 403 Forbidden before they reach the provider, whether the agent calls the MCP server or the Email API directly.

A read-only agent key is an IAM API key whose principal has read permissions only, bound to one grant. The Messages Reader system role (role_system_messages_reader) bundles the 4 permissions most reading agents need: messages.read, threads.read, folders.read, and drafts.read.

Each MCP tool needs one permission. With the Messages Reader role, the agent can call these tools:

MCP toolPermissionIn Messages Reader
list_messages, get_messagemessages.readYes
list_threadsthreads.readYes
list_folders, get_folder_by_idfolders.readYes
download_attachmentattachments.readNo, add it if needed
create_draft, update_draftdrafts.create, drafts.updateNo
send_messagemessages.sendNo
send_draftdrafts.sendNo
delete_draft, delete_eventdrafts.delete, events.deleteNo

The time tools (current_time, epoch_to_datetime, datetime_to_epoch) and confirm_send_message need no permission. An agent can call confirm_send_message, but the send_message call that follows still fails.

You need an Organization-bound IAM management key with the IAM Admin role, loaded as NYLAS_IAM_ADMIN_KEY. Create a management credential in the Dashboard covers the 4 steps. You also need the grant ID of the mailbox the agent reads, as NYLAS_GRANT_ID.

You can do everything below in the Dashboard instead, on the Nylas IAM page. The API is the better fit when your server creates a key for each user.

Create the principal with POST /v3/iam/principals, bound to the one grant the agent reads. The roles field takes the Messages Reader role, and direct_permissions adds attachments.read so the agent can open attachments up to the MCP server’s 10 MiB download limit. Leave direct_permissions out if the agent should only see message text.

Save data.id from the response as NYLAS_PRINCIPAL_ID. To cover several mailboxes for one user, bind the principal to a workspace instead, as shown in Limit an AI agent to one user’s accounts.

Create a credential on the principal with POST /v3/iam/principals/{principal_id}/credentials. The expires_at field is required and takes a Unix timestamp in seconds, up to 10 years ahead. A read-only agent that runs every day doesn’t need a long-lived key. 90 days is a reasonable default.

Nylas returns data.secret once. Store it in your secrets service as the agent’s NYLAS_API_KEY and don’t log the response.

The agent’s MCP client sends the read-only key as a Bearer token, like any API key connection. IAM checks the tool’s permission each time the agent calls it. Give the agent its grant ID in its instructions, because IAM keys can’t use /v3/grants/me.

Tell the agent in its instructions that it’s read-only. That saves it from attempting a send, failing, and retrying.

Test the boundary before you rely on it. This request tries to send a message with the read-only key. IAM checks the principal’s permissions before the request reaches the mailbox provider, so nothing is sent and the call returns 403 with the api.forbidden error type.

A GET /v3/grants/{grant_id}/messages?limit=1 request with the same key should return 200. The send_message MCP tool fails the same way, with the same message.

  • Read-only also means no labels or folders. Moving a message, marking it read, or applying a label needs messages.update. A triage agent that sorts mail needs that one permission added, and it still can’t send or delete.
  • Calendars and contacts need their own permissions. Messages Reader covers email only. Add calendars.read and events.read for an agent that reads schedules, or contacts.read for contacts.
  • Denials show up in Access Activity. Every denied request appears in the Dashboard’s Access Activity for 400 days, with the principal, key, and denial reason. Repeated denied sends from a read-only agent are a sign that something in its input is trying to steer it.
  • Role changes apply on the next request. If you later add a permission to the principal, existing keys pick it up without being reissued.
  • Provider scopes still apply. IAM can only narrow access. A grant authorized with read-only provider scopes stays read-only even under a key with send permission.