Manage the Agent Account Lifecycle

What is the agent account lifecycle?

The agent account lifecycle is the set of operations an account moves through from provisioning to retirement: create, inspect, rotate its credential, pause, and delete. Four of those map to verbs on the nylas agent account group; pause is the exception — there's no suspend verb, so it's done with a workspace rule. Either way, managing an agent's identity never requires the dashboard. Treating the account as a managed resource — not a one-time setup — is what keeps a fleet of agents auditable.

The stages matter most at the edges. Creation is trivial; the operations that carry risk are credential rotation when a key leaks and deletion when an agent is decommissioned. Getting those two right is the difference between an agent identity you can govern and one that lingers with stale access after the agent is gone.

How do I create and inspect an agent account?

Provisioning is one command. The nylas agent account create call returns a grant in under 2 seconds and auto-creates the managed connector on first use. Pass an optional --app-password at creation if the agent needs IMAP/SMTP access from a mail client:

nylas agent account create agent-01@yourapp.nylas.email

✓ Agent account created successfully!

Email:      agent-01@yourapp.nylas.email
Provider:   nylas
Status:     valid

Inspect a single account with nylas agent account get, which prints the email, provider, status, and the workspace ID that links the identity to its policy and rules. List every account in the application with nylas agent account list --json — the structured form a fleet audit iterates over:

nylas agent account get agent-01@yourapp.nylas.email

Email:        agent-01@yourapp.nylas.email
Provider:     nylas
Status:       valid
Workspace ID: ws_abc123

nylas agent account list --json | jq '.[] | {email, status}'

How do I check an account's status?

Two commands answer two different questions. The account's own health is the Status field from agent account get — a healthy account reads valid. The underlying managed connector's health is nylas agent status, which reports whether the nylas connector and configured accounts are ready.

nylas agent status

Wire the status check into a health probe rather than reading it by hand. A scheduled job that flags any account whose status isn't valid catches a broken identity before an agent fails mid-task. The agent account health guide builds that probe and an alert around it.

How do I rotate an account's app password?

When an agent uses IMAP or SMTP, its app password is a long-lived credential that needs rotating — on a schedule, and immediately if it leaks. The nylas agent account update command sets a new app password in place, so the agent's address and grant stay stable while the credential changes. The IMAP and SMTP clients pick up the new password on their next connection.

nylas agent account update agent-01@yourapp.nylas.email \
  --app-password "$(openssl rand -base64 24)"

Generating the password with openssl rand keeps a human from choosing a weak one and keeps the secret out of shell history when piped from a secrets manager. Rotate on offboarding, on suspected compromise, and on whatever cadence your security policy sets. Agents that only use the v3 API and the CLI don't need an app password at all — it's required only for direct IMAP/SMTP access, so the smallest credential surface is to skip it.

How do I pause an agent account?

There's no single "suspend" flag — pausing an agent account means cutting off what it can do, which the workspace already controls. To stop an agent from sending, attach an outbound rule that blocks all sends; the account stays alive and keeps receiving, but its outbound is frozen until you remove the rule. This is the reversible alternative to deletion when you need to halt an agent mid-incident.

# Freeze all outbound for an agent under investigation
nylas agent rule create \
  --name "PAUSE agent-01 outbound" \
  --trigger outbound \
  --condition recipient.domain,is_not,nonexistent.invalid \
  --action block

The condition matches every real recipient — no live mail goes to nonexistent.invalid — so the rule blocks all outbound. Because the rule lives on the workspace, the agent can't prompt its way past it; containment lives outside the agent's decision loop. Delete the rule to resume. For the full kill-switch pattern, see Stop Your AI Agent From Going Rogue.

How do I decommission an agent account?

When an agent retires, delete its account so no stale identity lingers. The nylas agent account delete command takes the account ID — not the email — and --yes skips the confirmation prompt for scripted teardown. Resolve the ID from the email with get --quiet first:

id=$(nylas agent account get agent-01@yourapp.nylas.email --quiet)
nylas agent account delete "$id" --yes

Deletion is the clean revocation: the grant goes away, so the address stops sending and receiving and any app password tied to it is dead. Unlike unlinking a person's OAuth session, there's no human account left behind — one agent, one grant, one deletion. Make decommission part of the agent's teardown script so a retired agent never leaves a working mailbox behind.

How do I manage many accounts' lifecycle at once?

The same verbs scale to a fleet because --json makes every list machine-readable. A nightly audit lists all accounts, flags any not in the valid state, and reports them — turning lifecycle from a manual chore into a scheduled check across dozens of identities:

nylas agent account list --json \
  | jq -r '.[] | select(.grant_status != "valid") | .email'

Pipe that list into a Slack alert or a teardown loop depending on the finding. When you're provisioning accounts at scale rather than auditing them, the provisioning-at-scale guide covers bulk creation, idempotent reruns, and per-tenant guardrails built on these same lifecycle commands.

Next steps

• Getting Started with Agent Accounts — the architecture behind the grant, workspace, and connector you manage here
• Provision Agent Accounts at Scale — bulk creation, idempotent reruns, and per-tenant guardrails on these lifecycle commands
• Monitor Agent Account Health — turn the status check into a scheduled probe with alerting
• Stop Your AI Agent From Going Rogue — the containment rules behind pausing an account
• Deploy Agent Accounts in Docker & CI — run these lifecycle commands headlessly from a container or pipeline
• Create an AI Agent Email Identity — the hands-on first-account walkthrough including app passwords
• Full command reference — every nylas agent account flag and subcommand
• Nylas v3 API documentation — the grants API behind these commands