# Agent Account IMAP SMTP Compatibility

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

## Direct Answer

An Agent Account is a Nylas-managed mailbox on `*.nylas.email` that your application reaches over the REST API by default — the same grant-scoped `/messages/send` path a connected Gmail or Outlook grant uses. For IMAP/SMTP compatibility, set an app password on the account: `nylas agent account create <email> --app-password '<pw>'`. That issues IMAP and SMTP-submission credentials so a legacy mail client or tool that cannot call the v3 API can still reach the mailbox. REST send stays primary; the app password is the compatibility fallback, not a replacement.

Omit `--app-password` and protocol-level access stays disabled. The password must be 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. Nylas stores it as a bcrypt hash, so it cannot be read back — rotate it with `nylas agent account update <id|email> --app-password '<pw>'`.

| Access path | How to enable | When to use |
|---|---|---|
| REST API send (primary) | Grant `grant_id` + API key, `POST /v3/grants/{id}/messages/send` | Default for agents and app code calling the v3 API |
| IMAP/SMTP client access | `--app-password` on the Agent Account | A legacy mail client or tool that speaks only IMAP/SMTP |
| External SMTP relay | A separate relay service, not a Nylas grant | Send-only with no managed inbox or unified API |

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.
- A legacy mail client or tool needs IMAP/SMTP access to the managed mailbox instead of the v3 API.
- 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 status --json
# Create the mailbox and issue IMAP/SMTP credentials in one step
nylas agent account create imap-smtp-compatibility@yourapp.nylas.email \
  --app-password 'ValidAgentPass123ABC!' \
  --json
# Rotate the IMAP/SMTP password later (bcrypt-hashed, so it can't be read back)
nylas agent account update imap-smtp-compatibility@yourapp.nylas.email \
  --app-password 'NewAgentPass456DEF!' \
  --json
nylas email send <agent-grant-id> \
  --to customer@example.com \
  --subject "Agent Account IMAP SMTP Compatibility" \
  --body "This message was sent by an app-owned agent account." \
  --yes \
  --json
```

The send step maps to one grant-scoped HTTP call, since an Agent Account is just a grant with a `grant_id`:

```bash
curl -s https://api.us.nylas.com/v3/grants/$AGENT_GRANT_ID/messages/send \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":[{"email":"customer@example.com"}],"subject":"Agent Account IMAP SMTP Compatibility","body":"Sent by an app-owned agent account."}'
```

### Python

```python
from nylas import Client

client = Client(api_key=api_key)
result = client.messages.send(identifier=agent_grant_id, request_body={
    "to": [{"email": "customer@example.com"}],
    "subject": "Agent Account IMAP SMTP Compatibility",
    "body": "Sent by an app-owned agent account.",
})
```

### TypeScript

```typescript
import Nylas from "nylas";

const nylas = new Nylas({ apiKey, apiUri: "https://api.us.nylas.com" });
const result = await nylas.messages.send({
  identifier: agentGrantId,
  requestBody: {
    to: [{ email: "customer@example.com" }],
    subject: "Agent Account IMAP SMTP Compatibility",
    body: "Sent by an app-owned agent account.",
  },
});
```

## Recommended Agent Workflow

1. Create or select one durable Agent Account for this responsibility.
2. Store the grant id with the tenant, environment, and workflow name.
3. Attach workspace policy and rules before increasing autonomy.
4. Return JSON results to the model instead of raw shell output.
5. Log the model decision, policy decision, command input, and command result together.

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

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. A free Agent Account caps outbound at 200 sends/day, surfaced as the policy field `limit_count_daily_email_sent`; inbox retention is governed by the separate `limit_inbox_retention_period` field (days). Once a grant crosses its daily cap, Nylas returns `429 rate_limit_error`, so retry workers must back off rather than loop.

## Minimum Data Contract

- tenant_id
- environment
- agent_account_email
- grant_id
- workspace_id
- policy_id
- rule_ids
- event_id
- dedupe_key
- command_result_id

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