Skip to content

ResourcesMembers

Members

Read who is in your organization, their role and which mailboxes they can open. Invite people and share mailboxes with them. Out-of-office settings live on each mailbox, not on the member.

Last updated

The member object

{
  "object": "member",
  "id": "mem_alice",
  "email": "alice@acme.com",
  "name": "Alice",
  "role": "admin",
  "mailbox_access": { "scope": "selected", "mailbox_ids": ["mbx_123"] },
  "created_at": "2026-01-01T00:00:00Z"
}

Member IDs have no fixed prefix. The accounts behind mailboxes are not people, so this API never returns them as members.

Roles are owner, admin, or member. Mailbox access does not depend on role. mailbox_access.scope is all or selected. With all, mailbox_ids is empty.

With selected, mailbox_ids lists only the granted mailboxes that the calling credential can itself reach, within its resource constraints. So the list may be incomplete, and an empty list can mean no grants or none you can see. A key with only members:read has no mail reach and returns no selected mailbox IDs.

List members

GET/v1/members

Scope: members:read. Supports cursor pagination with cursor and limit.

Retrieve a member

GET/v1/members/:id

Scope: members:read. Returns the member object or 404.

Invitations and mailbox sharing

An agent can invite colleagues and share mailboxes with them, but it never receives their credentials. The invitee gets the normal Shipmail invitation email and creates their own account.

These writes need members:write. No scope preset or agent profile includes it, not even Full access; an All access API key does. On an agent connection it is the Invite and share permission in Custom.

A write acts with the authority of the person behind the credential: the person who approved the OAuth connection, or who created the API key. That person must be an Owner or Admin, and can only share mailboxes they read themselves. Only a person who reads every mailbox can invite with all. A key restricted to mailboxes or domains can only share mailboxes inside its restriction and never invites with all.

The invitation object

{
  "object": "invitation",
  "id": "inv_sam",
  "email": "sam@acme.com",
  "role": "member",
  "mailbox_access": { "scope": "selected", "mailbox_ids": ["mbx_123"] },
  "newsletter_role": "editor",
  "created_at": "2026-10-27T09:00:00Z",
  "expires_at": "2026-10-29T09:00:00Z"
}

role is admin or member. mailbox_access has the same shape and the same visibility rule as on a member: with selected, only granted mailboxes the credential can reach are listed. A key with only members:read and members:write has no mail reach, so it gets an empty mailbox_ids list for selected access. newsletter_role is editor or null; only a member can be an editor.

List invitations

GET/v1/members/invitationsscope members:read

Returns pending, unexpired invitations, newest first, as { data: [...] }. There is no pagination: an organization has at most 100 pending invitations.

Invite a member

POST/v1/members/invitationsscope members:write
{
  "email": "sam@acme.com",
  "role": "member",
  "mailbox_access": "selected",
  "mailbox_ids": ["mbx_123"],
  "newsletter_role": "editor"
}
  • email and role are required.
  • mailbox_access defaults to selected. mailbox_ids takes at most 100 IDs and is ignored with all.
  • newsletter_role defaults to null and accepts editor for the member role only.

Returns 201 with the invitation. Send an Idempotency-Key header to retry safely. Errors: 403 authorization_error, 403 quota_exceeded when the team member limit is reached, 409 when the address already belongs to a member, has a pending invitation, or is a mailbox or alias address, and 422 for an invalid body or an address on one of the organization's own domains. Invite people with an address outside Shipmail, such as their personal email, so they can always sign in.

Cancel an invitation

DELETE/v1/members/invitations/:idscope members:write

Returns 204 with no body, or 404 when no pending invitation has that ID.

Share a mailbox with a member

PUT/v1/members/:id/mailboxes/:mailbox_idscope members:write

Shares one mailbox with a member who has selected access. No body. Returns the member object. Sharing a mailbox that is already shared returns the member unchanged. 403 when the member already has access to every mailbox, or the mailbox is outside the key restriction or the acting person's own access.

Unshare a mailbox from a member

DELETE/v1/members/:id/mailboxes/:mailbox_idscope members:write

Stops sharing one mailbox with the member and returns the member object. Removing a mailbox that is not shared returns the member unchanged.