Zapmail
Overview
API Reference
Overview
API Reference
  1. Capabilities
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Capabilities

Team Management

Workspaces separate domains, mailboxes and billing contexts under one account. This page covers creating workspaces, inviting people, changing their roles, and acting inside a specific workspace with the x-workspace-key header.

Roles#

RoleNotes
OWNERCreated automatically for the account that creates the workspace. Not listed as a member and cannot be assigned.
ADMINCan be invited and set as a role. May use x-workspace-key for the workspace.
EDITORCan be invited and set as a role.
VIEWERCan be invited and set as a role.

Work inside a workspace with x-workspace-key#

Send the optional header x-workspace-key with a workspace ID to run a request in that workspace. Without it, requests run in the key owner's primary workspace. The caller must be an OWNER or ADMIN of that workspace; otherwise the API returns 403, and an unknown workspace ID returns 404. A call that charges money bills the owner of the workspace: the key owner, or the workspace owner when the header points at a workspace owned by someone else.
Several list endpoints also accept a global flag that spans every workspace the key owner belongs to, whatever the role. List Workspaces (List Workspaces) shows the workspaces you can use and your role in each.

Manage workspaces#

1.
List Workspaces lists the workspaces the account owns or has joined, with domain and mailbox counts and billing details. The workspace selected by x-workspace-key is returned as currentWorkspace and left out of workspaces, so a page can hold fewer items than limit.
2.
Create Workspace creates a workspace owned by the account and adds the account as its OWNER. Names must be unique per owner (409 for a duplicate). Send billingDetails to save them in the same call, but note that the workspace is not rolled back if saving them fails. You can also save them later with Add Billing Details.
3.
Update Workspace renames a workspace and can update its billing details. The workspace must be owned by the account, otherwise 404. Billing details can also be changed with Update Billing Details.
4.
Move domains between workspaces with Move Domains to Another Workspace (see Domains).

Invite people and manage members#

1
Invite
Send Workspace Invitation with email, workspaceId and role (ADMIN, EDITOR or VIEWER). An invitation email is sent and the invitation expires after 48 hours. It returns 409 if the person is already a member or a non-expired pending invitation exists; an expired one is replaced. It returns 404 if the workspace does not exist or is not owned by the account.
2
Track
List Workspace Invitations lists invitations sent by the account across all its workspaces. status is PENDING, ACCEPTED, REJECTED, REVOKED or EXPIRED. All matching invitations come back in one response; page and limit only affect the pagination fields.
3
List members
List Workspace Members lists the members invited into workspaces owned by the account, across all of them. Use the returned id to change a role. The workspace field names each member's workspace.
4
Change a role
Update Member Role with memberId as a query parameter and role in the body (ADMIN, EDITOR or VIEWER). OWNER is rejected with 422. The change takes effect immediately and a workspace invitations webhook event with action role_changed is emitted.
5
Revoke access
Revoke Workspace Access with the person's email. A pending invitation is checked first and marked REVOKED; if there is none, the person is removed as a member. Only one record is affected per call, so call again to remove further invitations or memberships for the same email. The member loses access immediately.
totalSearchedCount on the members list is counted for the workspace selected by x-workspace-key, so it can be lower than the number of members returned across workspaces.
Related: Domains, Mailboxes, Webhooks, Authentication.
Previous
Zapbox
Next
ZapShield
Built with