The Lifecycle of an Agent Identity: Provision to Teardown

Every infrastructure team has a graveyard. Service accounts nobody remembers creating. API keys that outlived their project by three years. Credentials that still work and absolutely shouldn't. Email identities for AI agents are about to join that graveyard in large numbers — unless you treat them like infrastructure with a lifecycle: provisioned deliberately, auditable while alive, destroyed on purpose.

Here's that lifecycle, stage by stage, using Agent Accounts (currently in beta) as the concrete machinery.

Birth: a domain, then an address

An agent identity starts before the agent does, with a domain decision. Two options: a *.nylas.email trial domain that works instantly with zero DNS setup, or your own domain — registered once per organization, verified by publishing the MX record (inbound routing) and TXT records (ownership proof plus SPF/DKIM for outbound) at your DNS provider. Verification happens automatically once records propagate; the domain status flips to verified and it's ready to host accounts.

The recommended production pattern is a dedicated subdomain like agents.yourcompany.com, so the fleet's sender reputation stays isolated from your primary domain. Reputation is a domain-level asset; don't let an experimental agent spend it.

With a domain ready, birth is one call:

nylas agent account create sales-agent@agents.yourcompany.com

Prefer raw API? POST /v3/connect/custom with "provider": "nylas" does the same job — unlike OAuth providers, no refresh token is involved, just an address on a registered domain:

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "sales-agent@agents.yourcompany.com",
    "created_at": 1742932766
  }
}

The response includes the grant_id (data.id) — the identity's handle for everything that follows. Two birth-time decisions worth making consciously rather than by default: placement (pass a workspace_id so the account inherits that workspace's policy limits and rules; omit it and the account is auto-grouped by domain or dropped into the application default) and protocol access (an optional app_password — 18–40 printable ASCII characters with at least one uppercase, one lowercase, and one digit — enables IMAP/SMTP so humans can open the mailbox in Outlook or Apple Mail; it's bcrypt-hashed on write and can never be retrieved, only reset).

Work: one ID, the whole surface

While the agent lives, the grant_id is its entire interface. Messages, threads, drafts, folders, attachments — all the existing endpoints work against /v3/grants/{grant_id}/... exactly as they do for a human-connected account. The mailbox arrives with six system folders (inbox, sent, drafts, trash, junk, archive); custom folders can be added beside them.

The working identity also emits a steady event stream. Inbound mail runs the workspace's rules at the SMTP stage — block rejects a message before it's ever stored, mark_as_spam routes it to junk, assign_to_folder files it — and whatever survives fires message.created, identical in payload shape to the same webhook on any connected grant. Outbound, deliverability signals come back as message.send_success, message.send_failed, and message.bounce_detected, so every send the identity makes has a verdict you can record. An identity that's alive is an identity that's telling you things; silence on those triggers is itself a signal worth alerting on.

The fleet-management view matters as much as the single-account view. The CLI covers it without a dashboard visit:

nylas agent account list --json   # inventory
nylas agent status                # connector readiness
nylas agent policy list           # what governs whom

That inventory command is your defense against the graveyard. If agent account list returns something nobody can explain, you've found a zombie.

Audit: the mailbox is its own record

Here's where email identities beat most service credentials: the audit trail is built into the artifact. Every message the agent ever sent sits in its sent folder; every conversation is a thread you can fetch and read. The provisioning docs' verification step — send a test message in, then list the mailbox — doubles as the ongoing health check:

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

And because IMAP access shows the identical mailbox the API sees, a human reviewer can audit an agent by literally opening its mail. No log pipeline required for the first pass. The governance layer keeps its own books too: every rule that fires on inbound mail is logged as a rule evaluation you can query later, so "why did this message end up in junk?" has a recorded answer instead of a shrug.

One honest caveat before you lean your compliance story on this: the mailbox-as-audit-log has a retention horizon. On the free plan, inbox mail is retained for 30 days and spam for 7. If your audit requirements are measured in years, configure retention through the workspace policy or run an export job — don't discover the horizon during an investigation.

Mid-life changes don't require rebirth, either: move an account to a different workspace — different policy, different rules — with PATCH /v3/grants/{grant_id} and a new workspace_id. Governance evolves; the identity persists.

Death: delete on purpose

The stage everyone skips. An agent identity should die when its work ends — project shipped, test run finished, customer churned:

nylas agent account delete sales-agent@agents.yourcompany.com --yes

The discipline that makes this painless is pairing: whatever process creates an account owns its deletion. The docs' environment-separation pattern helps here too — staging agents live on agents.staging.yourcompany.com, so a sweep of stale staging identities can't touch production, and per-customer domains mean offboarding a tenant cleanly removes their agents with them.

Ephemeral identities aren't a workaround; they're the design. A mailbox that exists for one CI run and is gone an hour later never joins the graveyard.

Script both ends before you need either

Concrete next step: before your next agent ships, write the teardown script in the same PR as the provisioning script — create and delete, side by side, tested together. Then run nylas agent account list on whatever you have today.

Be honest: how many identities in that list could you explain right now?