# How to give an AI agent read-only email access

Source: https://developer.nylas.com/docs/cookbook/ai/mcp/read-only-email-agent/

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](/docs/v3/auth/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](/docs/dev-guide/mcp/) or the Email API directly.

## 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

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](/docs/v3/auth/nylas-iam/manage-principals-with-api/#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

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.

```bash
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](/docs/cookbook/ai/mcp/limit-agent-to-one-user/).

## 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.

```bash
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

The agent's MCP client sends the read-only key as a Bearer token, like any [API key connection](/docs/dev-guide/mcp/#connect-with-an-api-key). 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`.

```json [readOnlyMcp-MCP config]
{
  "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

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.

```bash
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" \
  --data '{"to": [{"email": "test@example.com"}], "subject": "Should fail", "body": "Blocked"}'
```

```json [readOnlyTest-Response (403)]
{
  "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

- **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.

## What's next

- [Nylas IAM permissions reference](/docs/v3/auth/nylas-iam/permissions/) lists every permission ID by group.
- [Manage IAM principals with the public API](/docs/v3/auth/nylas-iam/manage-principals-with-api/) covers updates, pagination, and troubleshooting.
- [Nylas MCP server](/docs/dev-guide/mcp/) lists every tool and its security guidance.
- [Limit an AI agent to one user's accounts](/docs/cookbook/ai/mcp/limit-agent-to-one-user/) scopes keys to a workspace of mailboxes.
- [Rotate an AI agent's API key](/docs/cookbook/ai/mcp/rotate-agent-api-key/) replaces a key without downtime.