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.
What a read-only agent key can do
Section titled “What a read-only agent key can do”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 tool | Permission | In Messages Reader |
|---|---|---|
list_messages, get_message | messages.read | Yes |
list_threads | threads.read | Yes |
list_folders, get_folder_by_id | folders.read | Yes |
download_attachment | attachments.read | No, add it if needed |
create_draft, update_draft | drafts.create, drafts.update | No |
send_message | messages.send | No |
send_draft | drafts.send | No |
delete_draft, delete_event | drafts.delete, events.delete | No |
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.
Before you begin
Section titled “Before you begin”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 a read-only principal
Section titled “Create a read-only principal”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.
curl --request POST \ --url "https://api.us.nylas.com/v3/iam/principals" \ --header "Authorization: Bearer $NYLAS_IAM_ADMIN_KEY" \ --header "Content-Type: application/json" \ --data "{ \"name\": \"Inbox summarizer\", \"description\": \"Read-only summarizer agent\", \"roles\": [\"role_system_messages_reader\"], \"direct_permissions\": [\"attachments.read\"], \"resource_binding\": {\"type\": \"grant\", \"id\": \"$NYLAS_GRANT_ID\"} }"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 the agent’s key
Section titled “Create the agent’s key”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.
EXPIRES_AT=$(( $(date +%s) + 90 * 86400 ))
curl --request POST \ --url "https://api.us.nylas.com/v3/iam/principals/$NYLAS_PRINCIPAL_ID/credentials" \ --header "Authorization: Bearer $NYLAS_IAM_ADMIN_KEY" \ --header "Content-Type: application/json" \ --data "{\"name\": \"Inbox summarizer key\", \"expires_at\": $EXPIRES_AT}"Nylas returns data.secret once. Store it in your secrets service as the agent’s NYLAS_API_KEY and don’t log the response.
Connect the agent to the MCP server
Section titled “Connect the agent to the MCP server”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.
{ "mcpServers": { "nylas": { "url": "https://mcp.us.nylas.com", "headers": { "Authorization": "Bearer <READ_ONLY_AGENT_KEY>" } } }}Tell the agent in its instructions that it’s read-only. That saves it from attempting a send, failing, and retrying.
Confirm that sending is blocked
Section titled “Confirm that sending is blocked”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.
curl --request POST \ --url "https://api.us.nylas.com/v3/grants/$NYLAS_GRANT_ID/messages/send" \ --header "Authorization: Bearer $READ_ONLY_AGENT_KEY" \ --header "Content-Type: application/json" \{ "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88", "error": { "type": "api.forbidden", "code": "api.forbidden", "message": "Principal is missing the required permission" }}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.
Things to know about read-only agent keys
Section titled “Things to know about read-only agent keys”- 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.readandevents.readfor an agent that reads schedules, orcontacts.readfor 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.
What’s next
Section titled “What’s next”- Nylas IAM permissions reference lists every permission ID by group.
- Manage IAM principals with the public API covers updates, pagination, and troubleshooting.
- Nylas MCP server lists every tool and its security guidance.
- Limit an AI agent to one user’s accounts scopes keys to a workspace of mailboxes.
- Rotate an AI agent’s API key replaces a key without downtime.