Subusers & Teams

Subusers let you create scoped operator accounts tied to individual team members. Each subuser has their own API keys, role-based permissions, and a credit allocation budget tracked independently from the parent workspace.

Create a Subuser Account

Subusers are created at the workspace level via POST /v1/users. A subuser can belong to only one workspace at creation time; workspace cross-access requires separate membership grants.

{create_subuser}

User creation fields

Field	Type	Required	Description
`email`	string	Yes	Unique email address for this user. Also their login identity.
`name`	string	Yes	Display name shown in the dashboard.
`role`	string	Yes	One of: `viewer`, `editor`, `operator`, `owner`.
`workspace_id`	string	Yes	Workspace this user belongs to.
`credits_allocated`	integer	No	Initial credit budget for this user. Defaults to 0 (no sends until allocated).
`mfa_required`	boolean	No	Enforce MFA for this user. Defaults to workspace setting.

List Subusers

{list_subusers}

Returns all subusers for the workspace with their role, credit breakdown, and last-seen timestamp.

Role-Based Access Control

Every subuser is assigned one of four roles. Roles are hierarchical and additive.

{role_permissions_table}

Role Definitions

Role	Typical use case
`viewer`	Stakeholders who need read-only access to analytics and delivery reports.
`editor`	Email marketers who create templates and campaigns but do not touch infrastructure.
`operator`	Send operations team managing webhooks, suppression lists, and daily send operations.
`owner`	Workspace administrators with full access including billing, user management, and security settings.

Subuser API Keys (Scoped to Subuser)

API keys can be created with a user_id binding. Such keys inherit the subuser role and are subject to the same permission boundaries. This is the recommended way to issue credentials to automated systems that should operate under a specific team member's identity.

{create_subuser_key}

Response — the key value is shown only once:

{subuser_key_response}

Subuser key limits: A subuser-bound key cannot be granted permissions beyond the subuser's own role. For example, a key bound to a viewer subuser cannot be given messages:send scope even if requested.

Subuser Credits Allocation and Tracking

Workspace credits are allocated to individual subusers. Each subuser draws from their own allocation when sending; they cannot spend credits allocated to other subusers in the same workspace.

Allocate additional credits to a subuser:

{allocate_credits}

Check credit balances:

{credit_balance}

Response:

{credit_balance_response}

When a subuser's available credits reach zero, all sending operations using their API key are rejected with 402 Payment Required until additional credits are allocated.

Team Management Dashboard

The PostMTA dashboard under App → Access provides a team management view where workspace owners can:

Invite new subusers by email.
Change roles (promote or demote).
Reset subuser passwords and MFA.
Allocate or reclaim credits.
Revoke all active sessions and API keys for a subuser.
View per-user send volume and credit usage charts.
Audit-log view of all actions taken by each subuser.

{team_dashboard}

API Key Permissions per Subuser

When you create a key for a subuser, you must specify explicit scopes. Scopes must be a subset of the subuser role's allowed permissions. The key cannot escalate its own permissions beyond the role.

Available scopes:

Scope	Description	Viewer	Editor	Operator	Owner
`messages:send`	Send email messages	-	+	+	+
`messages:read`	Read message status and history	+	+	+	+
`templates:write`	Create and update templates	-	+	+	+
`templates:read`	Read template definitions	+	+	+	+
`campaigns:write`	Create, pause, cancel campaigns	-	+	+	+
`campaigns:read`	Read campaign list and analytics	+	+	+	+
`suppressions:write`	Add or remove suppression entries	-	+	+	+
`suppressions:read`	List and search suppressions	-	+	+	+
`webhooks:write`	Create and manage webhooks	-	-	+	+
`ip-pools:write`	Manage IP pools and warmup	-	-	+	+
`users:write`	Manage subusers and roles	-	-	-	+
`credits:write`	Allocate and reclaim credits	-	-	-	+
`audit:read`	Read audit log entries	-	-	+	+