Skip to content
machinemail

Organization

The authenticated organization.

MethodPathSummary
GET/v0/organizationGet Organization (alias)
GET/v0/organizationsGet Organization
PATCH/v0/organizationsUpdate Organization
GET/v0/organizations/invitationsList Invitations
POST/v0/organizations/invitationsInvite Member
DELETE/v0/organizations/invitations/{invitation_id}Revoke Invitation
POST/v0/organizations/invitations/{invitation_id}/resendResend Invitation
GET/v0/organizations/membersList Members
PATCH/v0/organizations/members/{user_id}Update Member
DELETE/v0/organizations/members/{user_id}Remove Member

Get Organization (alias)

http
GET /v0/organization

Warning

Deprecated.

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)

organization_idstringRequired
ID of the organization.
namestringRequired
Name of the organization.
slugstringRequired
URL-safe name of the organization.
plan"free" | "pro" | "enterprise"Required
Plan of the organization.
inbox_countintegerRequired
Number of inboxes in the credential scope.
domain_countintegerRequired
Number of domains in the organization.
usageobject
Usage. Always present on GET /v0/organizations and PATCH /v0/organizations.
shared_domainstring
Domain every organization can create inboxes on, used when an inbox is created without domain. Always present on GET /v0/organizations and PATCH /v0/organizations.
updated_atstring (date-time)Required
Time at which the organization was last updated.
created_atstring (date-time)Required
Time at which the organization was created.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/organization" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "name": "Production",
  "slug": "string",
  "plan": "free",
  "inbox_count": 1,
  "domain_count": 1,
  "usage": {
    "message_count": 1,
    "storage_bytes": 2048,
    "messages_received_30d": 1,
    "messages_sent_30d": 1
  },
  "shared_domain": "string",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get Organization

http
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)

organization_idstringRequired
ID of the organization.
namestringRequired
Name of the organization.
slugstringRequired
URL-safe name of the organization.
plan"free" | "pro" | "enterprise"Required
Plan of the organization.
inbox_countintegerRequired
Number of inboxes in the credential scope.
domain_countintegerRequired
Number of domains in the organization.
usageobject
Usage. Always present on GET /v0/organizations and PATCH /v0/organizations.
shared_domainstring
Domain every organization can create inboxes on, used when an inbox is created without domain. Always present on GET /v0/organizations and PATCH /v0/organizations.
updated_atstring (date-time)Required
Time at which the organization was last updated.
created_atstring (date-time)Required
Time at which the organization was created.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/organizations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "name": "Production",
  "slug": "string",
  "plan": "free",
  "inbox_count": 1,
  "domain_count": 1,
  "usage": {
    "message_count": 1,
    "storage_bytes": 2048,
    "messages_received_30d": 1,
    "messages_sent_30d": 1
  },
  "shared_domain": "string",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Update Organization

http
PATCH /v0/organizations

Rename the 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.

namestring
New name. Must not be blank.

Response

200 The organization (application/json)

organization_idstringRequired
ID of the organization.
namestringRequired
Name of the organization.
slugstringRequired
URL-safe name of the organization.
plan"free" | "pro" | "enterprise"Required
Plan of the organization.
inbox_countintegerRequired
Number of inboxes in the credential scope.
domain_countintegerRequired
Number of domains in the organization.
usageobject
Usage. Always present on GET /v0/organizations and PATCH /v0/organizations.
shared_domainstring
Domain every organization can create inboxes on, used when an inbox is created without domain. Always present on GET /v0/organizations and PATCH /v0/organizations.
updated_atstring (date-time)Required
Time at which the organization was last updated.
created_atstring (date-time)Required
Time at which the organization was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X PATCH "https://api.machinemail.dev/v0/organizations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production"
}'
Response 200
{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "name": "Production",
  "slug": "string",
  "plan": "free",
  "inbox_count": 1,
  "domain_count": 1,
  "usage": {
    "message_count": 1,
    "storage_bytes": 2048,
    "messages_received_30d": 1,
    "messages_sent_30d": 1
  },
  "shared_domain": "string",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

List Invitations

http
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

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 Pending invitations (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.
invitationsInvitation[]Required
Pending invitations, newest first.

Each item of invitations is a Invitation:

invitation_idstringRequired
ID of the invitation.
organization_idstringRequired
ID of the organization the invitee joins.
emailstringRequired
Address the invitation was sent to. Only this address can accept it.
role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.
state"pending" | "accepted" | "expired" | "revoked"Required
State of the invitation.
invited_by_user_idstring
ID of the member who sent it, when known.
expires_atstring (date-time)Required
When the invitation stops working (7 days after it was sent).
created_atstring (date-time)Required
When the invitation was sent.
dev_linkstring
Development only (local sign-in with the noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the sign-in link that accepts the invitation.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/organizations/invitations" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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",
      "dev_link": "string"
    }
  ]
}

Invite Member

http
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. On a server without email-code sign-in (self-hosted or development), which signs people in with magic links, the email is a sign-in link and the invitation is accepted by signing in with that address.

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.

emailstringRequired
Address to invite.
role"owner" | "admin" | "member"
Role on joining. Default member. Only owners can invite owners.

Response

201 Sent (application/json)

invitation_idstringRequired
ID of the invitation.
organization_idstringRequired
ID of the organization the invitee joins.
emailstringRequired
Address the invitation was sent to. Only this address can accept it.
role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.
state"pending" | "accepted" | "expired" | "revoked"Required
State of the invitation.
invited_by_user_idstring
ID of the member who sent it, when known.
expires_atstring (date-time)Required
When the invitation stops working (7 days after it was sent).
created_atstring (date-time)Required
When the invitation was sent.
dev_linkstring
Development only (local sign-in with the noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the sign-in link that accepts the invitation.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
409Conflicts with an existing resource.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
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"
}'
Response 201
{
  "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",
  "dev_link": "string"
}

Revoke Invitation

http
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

invitation_idstringRequired
ID of the invitation.

Response

200 Revoked (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/organizations/invitations/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

Resend Invitation

http
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

invitation_idstringRequired
ID of the invitation.

Response

200 Sent again (application/json)

invitation_idstringRequired
ID of the invitation.
organization_idstringRequired
ID of the organization the invitee joins.
emailstringRequired
Address the invitation was sent to. Only this address can accept it.
role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.
state"pending" | "accepted" | "expired" | "revoked"Required
State of the invitation.
invited_by_user_idstring
ID of the member who sent it, when known.
expires_atstring (date-time)Required
When the invitation stops working (7 days after it was sent).
created_atstring (date-time)Required
When the invitation was sent.
dev_linkstring
Development only (local sign-in with the noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the sign-in link that accepts the invitation.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X POST "https://api.machinemail.dev/v0/organizations/invitations/string/resend" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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",
  "dev_link": "string"
}

List Members

http
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

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 members (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.
membersUser[]Required
Oldest first unless ascending=false.

Each item of members is a User:

user_idstringRequired
ID of the user.
emailstringRequired
Email address the user signs in with.
namestring | null
Display name, when set.
organization_idstringRequired
ID of the organization this record is about: the session’s active organization, or the organization listed.
role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.
created_atstring (date-time)Required
When the user was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/organizations/members" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "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"
    }
  ]
}

Update Member

http
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

user_idstringRequired
ID of the member (user_id).

Request body

Content type: application/json.

role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.

Response

200 The member (application/json)

user_idstringRequired
ID of the user.
emailstringRequired
Email address the user signs in with.
namestring | null
Display name, when set.
organization_idstringRequired
ID of the organization this record is about: the session’s active organization, or the organization listed.
role"owner" | "admin" | "member"Required
Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.
created_atstring (date-time)Required
When the user was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
409Conflicts with an existing resource.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
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"
}'
Response 200
{
  "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
  "email": "agent@machinemail.dev",
  "name": "Production",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "role": "owner",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Remove Member

http
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.

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

user_idstringRequired
ID of the member (user_id).

Response

200 Removed (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
409Conflicts with an existing resource.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/organizations/members/usr_01k6x3j0rw0000n8w4yc0g3q5s" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

On this page

Get Organization (alias)Get OrganizationUpdate OrganizationList InvitationsInvite MemberRevoke InvitationResend InvitationList MembersUpdate MemberRemove Member
0% read