Connected Apps · MachineMail Docs

Method	Path	Summary
`GET`	`/v0/oauth-grants`	List Connected Apps
`DELETE`	`/v0/oauth-grants/{grant_id}`	Disconnect App

List Connected Apps

http

GET /v0/oauth-grants

Apps and MCP clients people in the organization connected with OAuth. Requires an organization-scoped credential with api_key_read; pod, inbox and sandbox credentials get 403.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: none beyond a valid key.

Query parameters

limitinteger

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

page_tokenstring

next_page_token from the previous page.

ascendingboolean

Sort oldest first.

Response

200 A page of grants (application/json)

countintegerRequired

Number of items returned.

limitinteger

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_tokenstring

Page token for pagination. Absent on the last page.

oauth_grantsOAuthGrant[]Required

Newest first unless ascending is set.

Each item of oauth_grants is a OAuthGrant:

grant_idstringRequired

ID of the grant (oag_...).

client_idstringRequired

client_namestring | nullRequired

Self-reported by the client at registration.

client_uristring | nullRequired

logo_uristring | nullRequired

registration"dynamic" | "metadata_document"Required

user_idstringRequired

Who approved it.

user_emailstring | nullRequired

scopes

("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]

Required

resourcestringRequired

Audience of its access tokens.

pod_idstring | nullRequired

Set when the grant is limited to one pod.

inbox_idstring | nullRequired

Set when the grant is limited to one inbox.

created_atstring (date-time)Required

last_used_atstring (date-time) | nullRequired

Last token refresh or API call (updated at most once a minute).

expires_atstring (date-time)Required

When the current refresh token expires unless it is used (30 days after the last refresh).

Status	Meaning
`400`	Invalid request: error.type is validation and error.param names the field.
`401`	Missing, invalid, expired or revoked credential.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`500`	Unexpected server error.

Example

Request

curl "https://api.machinemail.dev/v0/oauth-grants" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "oauth_grants": [
    {
      "grant_id": "string",
      "client_id": "my-client-id",
      "client_name": "string",
      "client_uri": "https://example.com",
      "logo_uri": "https://example.com",
      "registration": "dynamic",
      "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
      "user_email": "agent@machinemail.dev",
      "scopes": ["inboxes.read"],
      "resource": "string",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "created_at": "2026-10-01T12:00:00.000Z",
      "last_used_at": "2026-10-01T12:00:00.000Z",
      "expires_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Disconnect App

http

DELETE /v0/oauth-grants/{grant_id}

Revokes the grant: its refresh token and every access token issued from it stop working immediately (401 on /mcp and /v0). Returns the grant as it was. Requires an organization-scoped credential with api_key_delete.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: none beyond a valid key.

Path parameters

grant_idstringRequired

ID of the grant (oag_...).

Response

200 The revoked grant (application/json)

grant_idstringRequired

ID of the grant (oag_...).

client_idstringRequired

client_namestring | nullRequired

Self-reported by the client at registration.

client_uristring | nullRequired

logo_uristring | nullRequired

registration"dynamic" | "metadata_document"Required

user_idstringRequired

Who approved it.

user_emailstring | nullRequired

scopes

("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]

Required

resourcestringRequired

Audience of its access tokens.

pod_idstring | nullRequired

Set when the grant is limited to one pod.

inbox_idstring | nullRequired

Set when the grant is limited to one inbox.

created_atstring (date-time)Required

last_used_atstring (date-time) | nullRequired

Last token refresh or API call (updated at most once a minute).

expires_atstring (date-time)Required

When the current refresh token expires unless it is used (30 days after the last refresh).

Errors

Status	Meaning
`401`	Missing, invalid, expired or revoked credential.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`500`	Unexpected server error.

Error bodies use the error envelope.

Example

Request

curl -X DELETE "https://api.machinemail.dev/v0/oauth-grants/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "grant_id": "string",
  "client_id": "my-client-id",
  "client_name": "string",
  "client_uri": "https://example.com",
  "logo_uri": "https://example.com",
  "registration": "dynamic",
  "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
  "user_email": "agent@machinemail.dev",
  "scopes": ["inboxes.read"],
  "resource": "string",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "created_at": "2026-10-01T12:00:00.000Z",
  "last_used_at": "2026-10-01T12:00:00.000Z",
  "expires_at": "2026-10-01T12:00:00.000Z"
}