# Quickstart: Agent Accounts

Source: https://developer.nylas.com/docs/v3/getting-started/agent-accounts/

Nylas **Agent Accounts** are fully functional email and calendar identities — real `name@company.com` mailboxes that Nylas hosts for you. You create and manage them entirely through the API, and they behave exactly like human-operated accounts to anyone interacting with them.

This quickstart walks through creating your first Agent Account and sending and receiving a message. For the full concept guide, see [What are Agent Accounts](/docs/v3/agent-accounts/).

Use an Agent Account when you want to:

- Give an AI agent a real email address it can send from, receive on, and RSVP to meetings with
- Run a system mailbox (`sales@`, `support@`, `scheduling@`) that your application owns end-to-end — no OAuth flow, no user's inbox to connect
- Spin up ephemeral mailboxes for workflows, projects, or individual customers

## Before you begin

You need a Nylas API key. If you haven't set up your account yet:

- **[Get started with the CLI](/docs/v3/getting-started/cli/)** — run `nylas init` to create an account and generate an API key in one command
- **[Get started with the Dashboard](/docs/v3/getting-started/dashboard/)** — the same steps through the web UI

## Pick a domain

Every Agent Account lives on a domain. You have two options:

- **Use a Nylas trial domain** — Nylas provides `*.nylas.email` subdomains for immediate testing. Register one from the Dashboard and you can create accounts like `test@<your-application>.nylas.email` right away.
- **Use your own domain** — register it in [Organization Settings → Domains](https://dashboard-v3.nylas.com/organization/domains), add the MX and TXT records Nylas gives you to your DNS provider, and Nylas verifies it automatically.

We recommend a dedicated subdomain for production use (for example, `agents.yourcompany.com`). See [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/) for the full flow, or [Managing domains](/docs/v3/email/domains/) for API-driven DNS setup.

## Create an Agent Account

### From the CLI

The quickest path is the [Nylas CLI](/docs/v3/getting-started/cli/). After `nylas init` you get a single command for creating Agent Accounts:

```bash
nylas agent account create test@your-application.nylas.email
```

The CLI prints the new grant ID alongside the status and connector details. You can list everything with `nylas agent account list` or confirm the connector is ready with `nylas agent status`. Agent Accounts also show up in `nylas auth list` alongside connected grants.

### From the Dashboard

On the left navigation, open **Agent Accounts → Accounts** and click **Create account**. Pick a registered domain and an alias — the account is live immediately.

### Programmatically

Use [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"`. Unlike OAuth providers, you don't need a refresh token — just the email address on a registered domain.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "test@your-application.nylas.email"
    }
  }'
```

The response contains a `grant_id`. **Save it** — you'll use it in every subsequent call. From this point on, the Agent Account works with every existing Nylas endpoint.

### (Optional) Place the account in a workspace

Policies and rules apply through [workspaces](/docs/v3/agent-accounts/policies-rules-lists/): attach a `policy_id` and `rule_ids` to a workspace, and every Agent Account in it inherits the limits, spam settings, and mail rules. Pass a top-level `workspace_id` to place the new account in a specific workspace; otherwise it lands in your application's default workspace.

```json
{
  "provider": "nylas",
  "workspace_id": "<WORKSPACE_ID>",
  "settings": {
    "email": "test@your-application.nylas.email"
  }
}
```

## Receive a message

Agent Accounts use the same messages API as any other Nylas grant.

### Option 1 — Poll the Messages endpoint

List the account's inbox with [`GET /v3/grants/{grant_id}/messages`](/docs/reference/api/messages/get-messages/):

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
```

To fetch a specific message including its body:

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
```

### Option 2 — Receive webhooks

Register a `message.created` webhook and Nylas will call your URL as soon as a message arrives. The payload is identical in shape to `message.created` for any other grant.

From the [Nylas CLI](/docs/v3/getting-started/cli/):

```bash
nylas webhook create \
  --url https://yourapp.example.com/webhooks/nylas \
  --triggers message.created
```

Or through the API:

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["message.created"],
    "callback_url": "https://yourapp.example.com/webhooks/nylas"
  }'
```

Example `message.created` payload for an Agent Account:

```json
{
  "specversion": "1.0",
  "type": "message.created",
  "id": "<WEBHOOK_ID>",
  "time": 1723821985,
  "webhook_delivery_attempt": 1,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "object": "message",
      "id": "<MESSAGE_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "subject": "Hello from Nylas",
      "from": [{ "email": "sender@example.com", "name": "Sender" }],
      "to": [{ "email": "test@your-application.nylas.email", "name": "" }],
      "date": 1723821981,
      "snippet": "This is a sample message"
    }
  }
}
```

For the full schema, see the [`message.created`](/docs/reference/notifications/messages/message-created/) webhook reference.

### Handle attachments

Inbound attachment limits are set by your plan and the grant's policy — tune `limit_attachment_size_limit`, `limit_attachment_count_limit`, and `limit_attachment_allowed_types` on the policy as needed. Attachment IDs come through on the message object; download with [`GET /v3/grants/{grant_id}/attachments/{attachment_id}/download`](/docs/reference/api/attachments/):

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
```

## Send a message

Send outbound mail with the same [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/) endpoint you use for any connected grant:

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Hello from my Agent Account",
    "body": "This message was sent by a Nylas Agent Account.",
    "to": [{ "email": "you@yourdomain.com", "name": "You" }]
  }'
```

The recipient sees a normal message from your Agent Account's address — no "sent via" branding, no relay footer.

## Use the calendar

Every Agent Account comes with a primary calendar. You can list events, create events, and RSVP to invitations through the same endpoints you use for any other grant:

- [`GET /v3/grants/{grant_id}/events`](/docs/reference/api/events/get-all-events/) — list events
- [`POST /v3/grants/{grant_id}/events`](/docs/reference/api/events/create-event/) — create an event and invite others
- [`POST /v3/grants/{grant_id}/events/{id}/send-rsvp`](/docs/reference/api/events/send-rsvp/) — accept or decline a received invitation; the RSVP is visible to every participant

Invitations arrive over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the Agent Account as a normal participant.

## Test it end-to-end

1. Send an email from any client (Gmail, your phone, etc.) to your Agent Account's address.
2. Confirm it arrives — either through the `message.created` webhook or by listing `/messages`.
3. Send a reply from the Agent Account using the `/send` endpoint above and verify it lands back in your client.

## What's next

- **[What are Agent Accounts](/docs/v3/agent-accounts/)** — the full concept guide, capabilities, and architecture
- **[Setup domains](/docs/v3/agent-accounts/dns-provider-setup/)**: register a custom domain and publish its DNS records
- **[Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/)**: multi-tenant patterns and programmatic account creation
- **[Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/)** — configure limits, spam detection, and inbound filtering
- **[BYO Auth reference — `nylas` provider](/docs/reference/api/manage-grants/byo_auth/)** — the full request body for programmatic creation
- **[Webhooks](/docs/v3/notifications/)** — full webhook configuration and notification schemas
- **[Messages API reference](/docs/reference/api/messages/get-messages/)** — complete endpoint documentation