docs(accounts): Update Account, pod and inbox account reads by sidharth0612 · Pull Request #256 · agentmail-to/agentmail-docs

sidharth0612 · 2026-09-21T01:33:49Z

Summary

Documents the account update API and the pod and inbox forms of the accounts resource. Matches agentmail-to/agentmail-api#1353.

New endpoints in the API reference

PATCH /v0/accounts/{account_id}/update
GET /v0/pods/{pod_id}/accounts, GET /v0/pods/{pod_id}/accounts/{account_id}
GET /v0/inboxes/{inbox_id}/accounts, GET /v0/inboxes/{inbox_id}/accounts/{account_id}

The update exists only on /accounts. The account ID is global, so the pod and inbox forms are read-only.

Schema

Account.status is optional and present only as disabled, with disabled_at beside it. An enabled account carries neither, so existing rows need no backfill.
UpdateAccountRequest.status takes its own enum, enabled | disabled. No null form.
ApiKeyPermissions gains account_update. Reads still need only inbox_read.
Update returns 400, 404 for an account outside the key's scope, and 409 on a concurrent write.

Also

Update Account's reference describes the full disable flow: finding the account_id, what the provider sees (access_denied, then invalid_grant), what is not revoked, that sign-in keys cannot hold account_update, and the 409 retry.
Changelog entry 2026-09-21.mdx (the day the route went live), and a pointer to Update Account from the AgentID sign-in guide.
openapi/openapi.yml and the CLI overrides gain the five new operations. bin/gen-cli-overrides.py --check passes.

Notes for review

Ready to merge. agentmail-to/agentmail-api#1353 merged on 2026-09-21, and the last successful Deploy Production run (1898afcc5) contains both the live route and the enabled | disabled contract. Verified against agentmail-api main at 11d0d0684.
Spec drift. Docker was unavailable locally, so the spec was produced with fern export and only the account-related hunks were applied. Pre-existing drift on main (Authorize Inbox response, APIKeys tag casing, and a few others) is untouched and will resolve when CI regenerates.

Test plan

fern check: 0 errors
python3 bin/gen-cli-overrides.py --check: overrides in sync with spec
Docs preview renders Accounts, Pods > Accounts, and Inboxes > Accounts

🤖 Generated with Claude Code

…_update permission Documents the account update API and the scoped account routes: POST /v0/accounts/{account_id}/update GET /v0/pods/{pod_id}/accounts GET /v0/pods/{pod_id}/accounts/{account_id} POST /v0/pods/{pod_id}/accounts/{account_id}/update GET /v0/inboxes/{inbox_id}/accounts GET /v0/inboxes/{inbox_id}/accounts/{account_id} POST /v0/inboxes/{inbox_id}/accounts/{account_id}/update Account gains a sparse `status` (present only as `disabled`) and `disabled_at`. The update request takes its own enum, `enabled | disabled`, so re-enabling needs no null and existing rows need no backfill. Adds the `account_update` permission to ApiKeyPermissions, a changelog entry, and a pointer from the AgentID sign-in guide. openapi/openapi.yml carries only the account-related hunks of a fresh export; the pre-existing drift on main is left for the CI regeneration. The seven new operations are annotated in the CLI overrides and bin/gen-cli-overrides.py --check passes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-09-21T01:34:33Z

📋 View the side-by-side API change review

The link expires in 7 days.

🔒 Your API specs are encrypted in CI before they're uploaded. The decryption key stays in this link's URL fragment (after the #), which browsers never send to a server, so oasdiff cannot read your specs. How it works →

_{Posted automatically by the oasdiff GitHub Action. To turn this off (no spec upload, no comment), set review: false on the action.}

github-actions · 2026-09-21T01:34:35Z

✨ API Changes

# API Changelog n/a vs. n/a


## API Changes

### GET /v0/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status


### GET /v0/accounts/{account_id}
-  added the optional property `disabled_at` to the response with the `200` status
-  added the optional property `status` to the response with the `200` status


### POST /v0/accounts/{account_id}/update
-  endpoint added


### GET /v0/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/api-keys/{api_key_id}
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}/accounts
-  endpoint added


### GET /v0/inboxes/{inbox_id}/accounts/{account_id}
-  endpoint added


### POST /v0/inboxes/{inbox_id}/accounts/{account_id}/update
-  endpoint added


### GET /v0/inboxes/{inbox_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/pods/{pod_id}/accounts
-  endpoint added


### GET /v0/pods/{pod_id}/accounts/{account_id}
-  endpoint added


### POST /v0/pods/{pod_id}/accounts/{account_id}/update
-  endpoint added


### GET /v0/pods/{pod_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `permissions/account_update` to the response with the `200` status


### PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/providers/{provider_id}/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status

💡 Download api-changelog-diff artifact or tag @fern Writer in #github-prs for changelog.

github-actions · 2026-09-21T01:36:54Z

🌿 Preview your docs: https://agentmail-preview-06fb213a-3274-4cb8-a3d3-8d776345ba90.docs.buildwithfern.com

Follows agentmail-to/agentmail-api#1353: the update is PATCH /v0/accounts/{account_id}/update, and the pod and inbox forms of the update are gone. The pod and inbox List and Get forms stay. Spec and CLI overrides rebuilt: five new operations instead of seven. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-09-21T01:44:22Z

✨ API Changes

# API Changelog n/a vs. n/a


## API Changes

### GET /v0/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status


### GET /v0/accounts/{account_id}
-  added the optional property `disabled_at` to the response with the `200` status
-  added the optional property `status` to the response with the `200` status


### PATCH /v0/accounts/{account_id}/update
-  endpoint added


### GET /v0/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/api-keys/{api_key_id}
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}/accounts
-  endpoint added


### GET /v0/inboxes/{inbox_id}/accounts/{account_id}
-  endpoint added


### GET /v0/inboxes/{inbox_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/pods/{pod_id}/accounts
-  endpoint added


### GET /v0/pods/{pod_id}/accounts/{account_id}
-  endpoint added


### GET /v0/pods/{pod_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `permissions/account_update` to the response with the `200` status


### PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/providers/{provider_id}/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status

💡 Download api-changelog-diff artifact or tag @fern Writer in #github-prs for changelog.

github-actions · 2026-09-21T01:47:15Z

🌿 Preview your docs: https://agentmail-preview-deba8ded-c151-4765-97b4-2af1596075e1.docs.buildwithfern.com

Update Account's reference now covers the whole disable flow: where the account_id comes from, that an account exists only after a first sign-in, what the provider sees once it is disabled (access_denied, then invalid_grant for an earlier code), what is not revoked, that sign-in keys cannot hold account_update, and what a 409 means. Same text in the Fern definition and the OpenAPI spec. Checked against agentmail-api main at 11d0d0684. The changelog entry moves to 2026-09-21, the day the route went live in prod. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-09-21T22:38:56Z

✨ API Changes

# API Changelog n/a vs. n/a


## API Changes

### GET /v0/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status


### GET /v0/accounts/{account_id}
-  added the optional property `disabled_at` to the response with the `200` status
-  added the optional property `status` to the response with the `200` status


### PATCH /v0/accounts/{account_id}/update
-  endpoint added


### GET /v0/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/api-keys/{api_key_id}
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/inboxes/{inbox_id}/accounts
-  endpoint added


### GET /v0/inboxes/{inbox_id}/accounts/{account_id}
-  endpoint added


### GET /v0/inboxes/{inbox_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/inboxes/{inbox_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: CreateApiKeyResponse]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/pods/{pod_id}/accounts
-  endpoint added


### GET /v0/pods/{pod_id}/accounts/{account_id}
-  endpoint added


### GET /v0/pods/{pod_id}/api-keys
-  added the optional property `api_keys/items/oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `api_keys/items/oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### POST /v0/pods/{pod_id}/api-keys
-  added the new optional request property `oneOf[subschema #1: CreateBearerApiKeyRequest]/allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the new optional request property `oneOf[subschema #2: CreatePublicKeyRequest]/permissions/account_update`
-  added the optional property `permissions/account_update` to the response with the `200` status


### PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}
-  added the new optional request property `allOf[subschema #1: ApiKeyMutableFields]/permissions/account_update`
-  added the optional property `oneOf[subschema #1: BearerApiKey]/permissions/account_update` to the response with the `200` status
-  added the optional property `oneOf[subschema #2: PublicKeyCredential]/permissions/account_update` to the response with the `200` status


### GET /v0/providers/{provider_id}/accounts
-  added the optional property `accounts/items/disabled_at` to the response with the `200` status
-  added the optional property `accounts/items/status` to the response with the `200` status

💡 Download api-changelog-diff artifact or tag @fern Writer in #github-prs for changelog.

github-actions · 2026-09-21T22:44:06Z

🌿 Preview your docs: https://agentmail-preview-f35ccfbe-24e2-419e-bf24-29694f2e430f.docs.buildwithfern.com

sidharth0612 changed the title ~~docs(accounts): Update Account, pod and inbox account routes~~ docs(accounts): Update Account, pod and inbox account reads Sep 21, 2026

duharry0915 approved these changes Sep 21, 2026

View reviewed changes

sidharth0612 merged commit d487690 into main Sep 21, 2026
4 checks passed

Navigation Menu

docs(accounts): Update Account, pod and inbox account reads - #256

docs(accounts): Update Account, pod and inbox account reads#256
sidharth0612 merged 3 commits into
mainfrom
claude/account-update-api-docs-95c46e

sidharth0612 commented Sep 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sidharth0612 commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes for review

Test plan

Uh oh!

github-actions Bot commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 View the side-by-side API change review

Uh oh!

github-actions Bot commented Sep 21, 2026

✨ API Changes

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

✨ API Changes

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

github-actions Bot commented Sep 21, 2026

✨ API Changes

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sidharth0612 commented Sep 21, 2026 •

edited

Loading

github-actions Bot commented Sep 21, 2026 •

edited

Loading