Skip to content
Skip to main content

Metadata for Agent Account events and email

Agent AccountsEmailCalendar

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

Section titled “Added”

  • Event metadata. Pass metadata on POST /v3/grants/{grant_id}/events or PUT /v3/grants/{grant_id}/events/{event_id}. The five reserved keys (key1 through key5) are indexed, so you can filter with ?metadata_pair=key1:demo-call on GET /events.

    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, PUT /messages/{message_id}, POST /drafts, and PUT /drafts/{draft_id}. Filter with ?metadata_pair=key1:onboarding on 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

Section titled “Updated docs”