# Metadata for Agent Account events and email

Source: https://developer.nylas.com/docs/changelogs/2026-08-20-agent-account-metadata/

Agent Account grants now accept the `metadata` object on Events, Messages, and Drafts. An agent can tag an object with its own identifiers on write and read them back on query, so correlating a Nylas object to a row in your own database no longer means parsing subject lines or event titles.

## Added

- **Event metadata.** Pass `metadata` on [`POST /v3/grants/{grant_id}/events`](/docs/reference/api/events/create-event/) or [`PUT /v3/grants/{grant_id}/events/{event_id}`](/docs/reference/api/events/put-events-id/). The five reserved keys (`key1` through `key5`) are indexed, so you can filter with `?metadata_pair=key1:demo-call` on [`GET /events`](/docs/reference/api/events/get-all-events/).

  ```bash
  curl --request POST \
    --url 'https://api.us.nylas.com/v3/grants/<AGENT_ACCOUNT_GRANT_ID>/events?calendar_id=primary' \
    --header 'Authorization: Bearer <NYLAS_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "Product demo",
      "when": { "start_time": 1755648000, "end_time": 1755651600 },
      "metadata": { "key1": "demo-call", "key2": "acct_8817" }
    }'
  ```

- **Message and draft metadata.** Pass `metadata` on [`POST /messages/send`](/docs/reference/api/messages/send-message/), [`PUT /messages/{message_id}`](/docs/reference/api/messages/put-messages-id/), [`POST /drafts`](/docs/reference/api/drafts/post-draft/), and [`PUT /drafts/{draft_id}`](/docs/reference/api/drafts/put-drafts-id/). Filter with `?metadata_pair=key1:onboarding` on [`GET /messages`](/docs/reference/api/messages/get-messages/). Metadata set on a draft carries through when the draft is sent.

- **Metadata in webhook payloads.** Objects that carry metadata include it in `*.created` and `*.updated` notifications, so an agent can route from the webhook alone without a follow-up read.

Limits match connected grants: up to 50 key-value pairs per object, keys up to 40 characters, values up to 500. `PUT` and `PATCH` overwrite the entire `metadata` object, so send every key you want to keep. Updating metadata doesn't generate its own webhook.

## Updated docs

- [Supported endpoints for Agent Accounts](/docs/v3/agent-accounts/supported-endpoints/#metadata) has a new Metadata section, and the entry is gone from the "Not currently supported" list.
- [How Agent Account calendars work](/docs/v3/agent-accounts/calendars/#metadata-on-events) covers event metadata and how it propagates across recurring instances.
- [Using metadata in Nylas](/docs/dev-guide/metadata/) notes Agent Account support alongside the reserved-key and filtering rules.