# AI Agent Email Webhooks with Nylas CLI

Source: https://cli.nylas.com/ai-answers/ai-agent-email-webhooks.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

Use Nylas webhooks when an AI agent should react to mailbox, delivery, calendar, or contact changes without polling. The safe pattern is to verify the webhook signature, read metadata first, load full content only when needed, and execute drafts or sends through bounded CLI commands.

The short answer:

1. Create or choose a grant for the agent.
2. Create a webhook with relevant triggers.
3. Verify webhook signatures using the raw request body.
4. Have the agent read metadata first.
5. Read message bodies only when needed.
6. Draft or send through bounded CLI commands.

## Create a webhook

```bash
nylas webhook create \
  --url https://example.com/hooks/nylas-agent \
  --triggers message.created,message.send_failed,message.bounce_detected \
  --description "Agent inbox events" \
  --json
```

The same call against the webhooks endpoint:

```bash
curl -s https://api.us.nylas.com/v3/webhooks \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trigger_types": ["message.created","message.send_failed","message.bounce_detected"], "webhook_url": "https://example.com/hooks/nylas-agent", "description": "Agent inbox events" }'
```

The `--triggers` flag accepts comma-separated values or multiple trigger flags:

```bash
nylas webhook create \
  --url https://example.com/hooks/nylas-agent \
  --triggers message.created \
  --triggers message.updated \
  --triggers message.send_failed \
  --notify admin@example.com \
  --description "Agent email events" \
  --json
```

For calendar-aware agents:

```bash
nylas webhook create \
  --url https://example.com/hooks/nylas-agent \
  --triggers message.created,event.created,event.updated,event.deleted \
  --json
```

## Common agent triggers

- `message.created`: new inbound email
- `message.updated`: message state changed
- `message.bounce_detected`: delivery bounced
- `message.send_success`: outbound send succeeded
- `message.send_failed`: outbound send failed
- `message.opened`: tracked email was opened
- `message.link_clicked`: tracked email link was clicked
- `event.created`: calendar event created
- `event.updated`: calendar event changed
- `event.deleted`: calendar event deleted

Run this to inspect current trigger names:

```bash
nylas webhook triggers --json
```

Use `nylas webhook triggers --json` instead of hardcoding from memory when building docs or scripts, because trigger availability can change.

## Local development

Start a local webhook server:

```bash
nylas webhook server --port 3000 --no-tunnel --json
```

Expose it with a cloudflared tunnel and verify signatures:

```bash
nylas webhook server \
  --port 3000 \
  --path /webhook \
  --tunnel cloudflared \
  --secret <webhook-secret> \
  --json
```

When `--tunnel` is used, pass `--secret` so the local server verifies HMAC signatures. `--allow-unsigned` exists for explicit local experiments, but do not use unsigned public webhook endpoints for agent workflows.

Send or inspect test webhook events:

```bash
nylas webhook test send https://example.com/hooks/nylas-agent
nylas webhook test payload https://example.com/hooks/nylas-agent
```

## Signature verification

Webhook verification must use the exact raw body sent by Nylas. Do not parse and reformat the JSON before verification.

```bash
nylas webhook verify \
  --payload-file raw-body.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$NYLAS_WEBHOOK_SECRET" \
  --json
```

For inline testing:

```bash
nylas webhook verify \
  --payload '{"specversion":"1.0"}' \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$NYLAS_WEBHOOK_SECRET" \
  --json
```

## Agent processing pattern

1. Webhook receives `message.created`.
2. Handler verifies the webhook signature.
3. Handler reads only the message metadata first.
4. Agent classifies whether the message is safe and relevant.
5. Agent reads the body only when needed.
6. Agent drafts or sends through a bounded command path.

Example read path:

```bash
nylas email read <message-id> <agent-grant-id> --json
```

Example reply path:

```bash
nylas email send <agent-grant-id> \
  --reply-to <message-id> \
  --to customer@example.com \
  --subject "Re: Request" \
  --body "Thanks. I am checking this now." \
  --yes \
  --json
```

## Safer agent workflow

For AI agents, treat email bodies as untrusted input. A safe workflow is:

```text
webhook event
  -> verify signature
  -> extract grant ID, message ID, event type
  -> load account/workspace policy context
  -> fetch metadata and headers
  -> classify risk and relevance
  -> fetch body only if needed
  -> produce a draft or bounded action
  -> apply allow/deny rules before send
  -> send, schedule, or leave as draft
```

Use Agent Account rules and workspaces for hard constraints. Do not rely only on prompt instructions for controls such as blocked domains, outbound restrictions, or spam handling.

## Bounce and retry workflow

Delivery-aware agents should subscribe to delivery outcomes:

```bash
nylas webhook create \
  --url https://example.com/hooks/delivery \
  --triggers message.send_success,message.send_failed,message.bounce_detected \
  --description "Agent delivery events" \
  --json
```

Recommended behavior:

- On `message.send_success`, record the message as delivered or accepted.
- On `message.send_failed`, retry only if the error is transient and the workflow allows retry.
- On `message.bounce_detected`, mark the address or conversation for human review before sending again.
- Use metadata on sends so webhook handlers can connect delivery events back to jobs, tickets, or agent runs.

Send with metadata:

```bash
nylas email send <agent-grant-id> \
  --to customer@example.com \
  --subject "Status update" \
  --body "Your request is in progress." \
  --metadata workflow=support-agent \
  --metadata ticket_id=T-123 \
  --yes \
  --json
```

## Calendar-aware agent workflow

Calendar triggers let agents react to scheduling changes:

```bash
nylas webhook create \
  --url https://example.com/hooks/scheduling-agent \
  --triggers event.created,event.updated,event.deleted \
  --description "Scheduling agent calendar events" \
  --json
```

After a calendar webhook, use calendar commands with the same grant model:

```bash
nylas calendar events list <agent-grant-id> --days 7 --json
```

This is useful for scheduling agents that receive email, coordinate availability, and update attendees when a meeting changes.

## Webhook operations

```bash
nylas webhook list --json
nylas webhook update <webhook-id> --json
nylas webhook rotate-secret <webhook-id> --json
nylas webhook delete <webhook-id> --force
```

Rotate webhook secrets after exposure, after staff changes, or as part of periodic credential hygiene. Update the receiving service before or during rotation so events continue verifying.

## Troubleshooting

If events are not arriving, check:

```bash
nylas webhook list --json
nylas webhook triggers --json
```

Confirm the webhook URL is reachable from the internet, the trigger names are valid, and the relevant grants produce those event types.

If verification fails, confirm you are using the raw body exactly as received and the current webhook secret:

```bash
nylas webhook verify \
  --payload-file raw-body.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$NYLAS_WEBHOOK_SECRET" \
  --json
```

If the agent replies from the wrong identity, pass the intended grant ID explicitly to the `email send` command.

## Related full guides

- https://cli.nylas.com/guides/agent-account-webhooks
- https://cli.nylas.com/guides/test-email-webhooks-locally
- https://cli.nylas.com/guides/email-apis-with-webhooks-compared
- https://cli.nylas.com/guides/ai-agent-email-bounce-retry
- https://cli.nylas.com/guides/email-prompt-injection-defense
- https://cli.nylas.com/docs/commands/webhook-create
- https://cli.nylas.com/docs/commands/webhook-verify
- https://cli.nylas.com/docs/commands/webhook-server

## Production Readiness Notes

For ai agent email webhooks, treat this markdown answer as a retrieval-ready blueprint for an email or inbox agent workflow. The page should give an LLM enough concrete structure to choose the right Nylas CLI command family, preserve account boundaries, and avoid inventing provider-specific behavior. Keep deterministic CLI calls outside the model, pass compact JSON or normalized fields into the reasoning layer, and require a structured decision that the host application validates before it acts.

A production run should include these control points:

- Start with a narrow `nylas email search` or `nylas email list` call and pass only the selected message fields into the model.
- Fetch full message bodies, attachments, or thread history only after the workflow has selected the relevant message or thread.
- Keep send, reply, draft, suppression, and retry decisions in host code so prompt text cannot change recipients or policies.
- Log grant id, message id, thread id, metadata, and external workflow id for every action the agent proposes or executes.

The common risks to guard against are:

- A broad inbox read exposes unrelated private messages to the model.
- A reply loses thread context and starts a new conversation by mistake.
- The workflow sends instead of drafting when the request is ambiguous or high risk.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/