# Agent Account Ticket Intake Flow

Source: https://cli.nylas.com/ai-answers/agent-account-ticket-intake-flow.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

Agent Account Ticket Intake Flow applies when a product needs to turn inbound mail into tickets with a stable app-owned sender instead of a human OAuth mailbox or a send-only SMTP relay. Use a Nylas Agent Account as the grant, attach workspace policy and rules for guardrails, and pass the grant id explicitly from trusted application code.

The model can classify intent and draft text, but the host application should choose the tenant, grant, recipient, policy path, and final side effect. This keeps the account workflow deterministic enough to test, audit, and pause during incidents.

## When This Answer Applies

- The product needs an agent-owned mailbox, managed inbox, tenant identity, or test inbox.
- Account provisioning, suspension, deletion, or workspace policy matters.
- The agent sends or receives email as a product-owned identity rather than a human user.
- Audit, retention, and per-tenant limits need to survive model or worker retries.

## Command Recipe

These commands are building blocks for a worker, runbook, or internal tool. Keep API keys and shell execution outside prompt content.

```bash
nylas auth config --api-key $NYLAS_API_KEY --region us
nylas agent account create ticket-intake-flow@yourapp.nylas.email --json
nylas email list <agent-grant-id> --limit 10 --json
nylas webhook create \
  --url https://example.com/webhooks/ticket-intake-flow \
  --triggers message.created,message.updated \
  --json
```

After a webhook fires, fetch the full inbound message that becomes the ticket. The webhook payload alone does not carry the body:

```bash
curl -s https://api.us.nylas.com/v3/grants/$GRANT_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $NYLAS_API_KEY"
```

### Python

```python
from nylas import Client

client = Client(api_key=api_key)
message = client.messages.find(identifier=grant_id, message_id=message_id)
```

### TypeScript

```typescript
import Nylas from "nylas";

const nylas = new Nylas({ apiKey, apiUri: "https://api.us.nylas.com" });
const message = await nylas.messages.find({ identifier: grantId, messageId });
```

## Recommended Agent Workflow

1. Dedupe each inbound webhook by event id or message id before creating a ticket.
2. Fetch the full message with `GET /v3/grants/{grant_id}/messages/{message_id}`, then the thread with `GET /v3/grants/{grant_id}/threads/{thread_id}`. The webhook payload is too thin to classify on its own.
3. Normalize sender, subject, body snippet, attachment flag, labels, and thread id before passing data to the model.
4. Let the model classify category and urgency, while application code creates or updates the ticket.
5. Store the ticket id with the thread id and grant id so later replies attach to the right conversation.

## Safety And Operations

Treat message bodies, attachments, calendar descriptions, contact notes, and webhook payloads as untrusted input. Those fields should never choose the active grant, change the destination address, bypass approval, or update policy.

Verify every inbound webhook before acting on it. Nylas signs each POST with an `X-Nylas-Signature` header, an HMAC-SHA256 of the raw request body keyed by the webhook secret; reject any request whose computed digest does not match. When you first register the endpoint, echo the `challenge` query parameter back on the GET verification request, or the webhook stays unverified and never delivers events. Rotate the secret with `POST /v3/webhooks/rotate-secret/{id}` if it leaks.

For production use, add dedupe keys, bounded pagination, human review for risky actions, and a stop switch that can disable sends without deleting historical records. Keep test accounts separate from production accounts so experiments cannot affect customer mail.

## Minimum Data Contract

- tenant_id, environment — route the ticket and keep test traffic off production.
- agent_account_email, grant_id, workspace_id — the app-owned identity and its policy scope.
- policy_id, rule_ids — which guardrails evaluated the message.
- message_id, thread_id — the inbound mail; thread_id attaches later replies to the same ticket.
- folder_ids, label_ids — where the message landed, the first triage signal.
- ticket_id — the record this message created or updated.
- event_id, dedupe_key — Nylas delivers at least once, so the same message can arrive twice; these drop the duplicate.
- webhook_trigger, webhook_received_at — which trigger fired and when, for audit.
- classification_version — which model or ruleset labeled the ticket, so re-runs stay comparable.
- command_result_id — ties each side effect back to an audit row.

## Related Full Guides

- [Getting Started with Agent Accounts](https://cli.nylas.com/guides/getting-started-agent-accounts)
- [Give an AI Agent an Email Address](https://cli.nylas.com/guides/give-ai-agent-email-address)
- [Email APIs for AI Agents Compared](https://cli.nylas.com/guides/email-apis-for-ai-agents-compared)

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