title: "Organization" description: "Read, update and delete your MachineMail organization, invite and manage its members, and check the plan, its allowances and usage in the current period." canonical: "https://machinemail.dev/docs/reference/api/organization"

Organization

Read, update and delete your MachineMail organization, invite and manage its members, and check the plan, its allowances and usage in the current period.

Source: https://machinemail.dev/docs/reference/api/organization

Get Organization (alias)

GET /v0/organization

Alias of GET /v0/organizations.

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

Response

200 The organization (application/json)

Errors

Example

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

{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "name": "Production",
  "slug": "string",
  "plan": "free",
  "inbox_count": 1,
  "domain_count": 1,
  "domain_limit": 1,
  "usage": {
    "message_count": 1,
    "storage_bytes": 2048,
    "messages_received_30d": 1,
    "messages_sent_30d": 1
  },
  "shared_domain": "string",
  "undo_send": true,
  "default_inbox_id": "acme@machinemail.dev",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get Organization

GET /v0/organizations

The organization of the credential, with inbox and domain counts and usage. inbox_count and usage count what the credential can see (a pod key: its pod).

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

Response

200 The organization (application/json)

Errors

Example

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

Update Organization

PATCH /v0/organizations

Rename the organization, turn undo send in the dashboard on or off (undo_send), or change the default inbox (default_inbox_id).

The organization slug is fixed when it is created and never changes: a different slug in the body is 400 (the current value is accepted and ignored). The slug reserves {slug}@ on the shared domain for this organization.

Organization-scoped credentials only: pod and inbox credentials get 403.

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

Request body

Content type: application/json.

Response

200 The organization (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/organizations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production"
}'

Delete Organization

DELETE /v0/organizations

Delete the organization, with the code emailed by POST /v0/organizations/deletion. It cannot be undone.

Access ends at once: every member's dashboard sessions and open streams for the organization stop working, every API key is revoked, connected apps and agents are disconnected, pending invitations are revoked, webhooks stop, and mail to the organization's addresses is refused as unknown. Its inboxes, messages, attachments, drafts, threads, domains, webhooks, events, pods and lists are then removed in the background. The slug stays reserved: no organization can use it again. Your session moves to another organization you belong to (as when leaving one); when there is none, it ends and the mm_session cookie is cleared.

Owners only, from a dashboard session (the mm_session cookie): admins, members, API keys and access tokens get 403.

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

Request body

Content type: application/json.

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/organizations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

{
  "ok": true,
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e"
}

Start Deleting Organization

POST /v0/organizations/deletion

First step of deleting the organization: send confirm_name, the organization's name (any case), and a 6-digit confirmation code is emailed to you. The code works once, for 10 minutes and 3 tries; asking again sends a new one (at most 3 an hour, and 10 a day for the organization). 502 when the email could not be sent: no code exists, try again. Then confirm with DELETE /v0/organizations.

409 with code: billing_subscription_active while a paid plan is in force: cancel it under Billing first, and delete the organization once the plan has ended.

Owners only, from a dashboard session (the mm_session cookie): admins, members, API keys and access tokens get 403.

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

Request body

Content type: application/json.

Response

202 Code sent (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/organizations/deletion" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm_name": "string"
}'

{
  "email": "agent@machinemail.dev",
  "expires_at": "2026-10-01T12:00:00.000Z"
}

List Invitations

GET /v0/organizations/invitations

Pending invitations, newest first (ascending=true: oldest first). Dashboard session only (the mm_session cookie): API keys and access tokens get 403. Owners and admins manage members; only owners grant, change or remove the owner role.

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

Query parameters

Response

200 Pending invitations (application/json)

Each item of invitations is a Invitation:

Errors

Error bodies use the error envelope.

Example

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

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "invitations": [
    {
      "invitation_id": "string",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "email": "agent@machinemail.dev",
      "role": "owner",
      "state": "pending",
      "invited_by_user_id": "string",
      "expires_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Invite Member

POST /v0/organizations/invitations

Email an invitation to join the organization, valid for 7 days and only for that address. 409 when the address is already a member or already invited.

The email links to /invite/{token}, where the person signs in (email code, social or SSO) and accepts it.

403 with error.code signup_address_not_allowed when the address is on a MachineMail domain (the shared domain, or a subdomain of it): those addresses can’t be used for accounts. The answer depends on the address’s domain only, never on whether it has an account. An address on a custom domain verified on MachineMail can be invited, but someone without an account can accept only an invitation from the organization that verified the domain; those people can join that organization but not create organizations of their own.

Dashboard session only (the mm_session cookie): API keys and access tokens get 403. Owners and admins manage members; only owners grant, change or remove the owner role.

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

Request body

Content type: application/json.

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/organizations/invitations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev"
}'

{
  "invitation_id": "string",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "email": "agent@machinemail.dev",
  "role": "owner",
  "state": "pending",
  "invited_by_user_id": "string",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Revoke Invitation

DELETE /v0/organizations/invitations/{invitation_id}

Revoke a pending invitation: its link stops working. Dashboard session only (the mm_session cookie): API keys and access tokens get 403. Owners and admins manage members; only owners grant, change or remove the owner role.

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

Path parameters

Response

200 Revoked (application/json)

Errors

Error bodies use the error envelope.

Example

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

{
  "ok": true
}

Resend Invitation

POST /v0/organizations/invitations/{invitation_id}/resend

Send a pending invitation again. Dashboard session only (the mm_session cookie): API keys and access tokens get 403. Owners and admins manage members; only owners grant, change or remove the owner role.

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

Path parameters

Response

200 Sent again (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/organizations/invitations/string/resend" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "invitation_id": "string",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "email": "agent@machinemail.dev",
  "role": "owner",
  "state": "pending",
  "invited_by_user_id": "string",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

List Members

GET /v0/organizations/members

The people who sign in to the dashboard for this organization, with their role in it, oldest first. Organization-scoped credentials only: pod and inbox credentials get 403.

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

Query parameters

Response

200 A page of members (application/json)

Each item of members is a Member:

Errors

Error bodies use the error envelope.

Example

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

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "members": [
    {
      "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
      "email": "agent@machinemail.dev",
      "name": "Production",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "role": "owner",
      "created_at": "2026-10-01T12:00:00.000Z",
      "sign_in_methods": ["email"],
      "last_sign_in_method": "email"
    }
  ]
}

Update Member

PATCH /v0/organizations/members/{user_id}

Change a member's role. The last owner cannot be demoted (409). Dashboard session only (the mm_session cookie): API keys and access tokens get 403. Owners and admins manage members; only owners grant, change or remove the owner role.

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

Path parameters

Request body

Content type: application/json.

Response

200 The member (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/organizations/members/usr_01k6x3j0rw0000n8w4yc0g3q5s" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "owner"
}'

{
  "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
  "email": "agent@machinemail.dev",
  "name": "Production",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "role": "owner",
  "created_at": "2026-10-01T12:00:00.000Z",
  "sign_in_methods": ["email"],
  "last_sign_in_method": "email"
}

Remove Member

DELETE /v0/organizations/members/{user_id}

Remove a member, or leave the organization with your own user_id (any role). The last owner cannot leave or be removed (409).

Their access ends at once: their dashboard sessions and open event streams for this organization stop working, the API keys they created here are revoked (CLI keys, and keys minted with those keys, included), the apps they connected with OAuth (MCP clients) are disconnected, and invitations they sent that are still pending are revoked. Keys that record no creator (made before organizations had members) are not revoked: review them under API keys. Leaving moves your session to another organization you belong to whose sign-in policy your session meets (its single sign-on and sign-in method rules apply, as for switching); when there is none, the session ends and the mm_session cookie is cleared.

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

Path parameters

Response

200 Removed (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/organizations/members/usr_01k6x3j0rw0000n8w4yc0g3q5s" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

Get Plan Usage

GET /v0/organizations/usage

The plan of the organization, its allowances and its usage in the current period: a calendar month in UTC, with the daily cap resetting at UTC midnight.

Inbound messages count once each; outbound messages count once per distinct recipient (to, cc and bcc). Spam and quarantined mail never count (mail your own receive lists block does). Storage includes drafts and held mail. Deleting mail frees storage but does not give back messages already counted.

On the Free plan, inbound mail past an allowance is held (held) and delivered when the allowance resets or after an upgrade; sends past it are refused with 402 plan_limit_exceeded. Paid plans are never blocked: usage past an allowance is billed as overage.

Organization-wide whatever the credential: Organization-scoped credentials only: pod and inbox credentials get 403.

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

Response

200 Plan allowances and usage (application/json)

limits is a PlanLimits:

Errors

Error bodies use the error envelope.

Example

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

{
  "plan": "free",
  "period": {
    "start": "2026-10-01T12:00:00.000Z",
    "resets_at": "2026-10-01T12:00:00.000Z",
    "day_resets_at": "2026-10-01T12:00:00.000Z"
  },
  "limits": {
    "messages_per_month": 1,
    "messages_per_day": 1,
    "inbound_per_month": 1,
    "outbound_per_month": 1,
    "storage_bytes": 2048,
    "custom_domains": 1,
    "seats": 1,
    "overage": false
  },
  "usage": {
    "inbound": 1,
    "outbound": 1,
    "messages": 1,
    "messages_today": 1,
    "storage_bytes": 2048,
    "custom_domains": 1,
    "seats": 1
  },
  "held": {
    "count": 1,
    "bytes": 2048,
    "oldest_at": "2026-10-01T12:00:00.000Z"
  },
  "enforcement": "enforce"
}