Organisation API overview

Model your customers as workspaces, not subaccounts: every tenant gets its own domains, keys, suppressions, webhooks, limits and users, and an organisation key manages them all through the API.

Organisation API — workspaces, not subaccounts

Other providers model a SaaS platform's customers as subaccounts — records inside one account that share its keys, suppressions and reputation. wemail models them as workspaces: each one is a full account under your organisation, with its own sending domains, API keys, suppression lists, webhooks, templates, members, rate limits and monthly allocation. A customer can never see or affect another customer, and sharing between workspaces (a common suppression list, a shared domain, a shared dedicated IP) is explicit and opt-in, per resource and per direction.

The Organisation API is how a platform or reseller drives this by code. It is authenticated with an organisation key (afn_org_…), a separate kind of credential created in Settings → Organisation → API access by the organisation owner (two-factor authentication required). One sentence sums up the model: workspace keys act inside a workspace; organisation keys act on workspaces.

What an organisation key can do

• Workspaces — list, create, rename, archive and restore them.
• Workspace API keys — mint a key for a workspace (the secret is returned once — hand it to your customer), rotate it, revoke it.
• Limits — set a workspace's monthly allocation from the organisation pool, pause or resume its sending.
• Usage — read each workspace's usage, the same numbers it sees itself, plus an organisation roll-up.
• Members — invite people to a workspace, change their role, remove them.
• Audit — read the organisation-wide audit log, including everything done through this API.

What it can never do

An organisation key cannot send, verify or validate; cannot read or change a workspace's domains, templates, suppressions, webhooks, uploads or routing; cannot read messages, events or activity; cannot touch billing, plans, payment methods or sign-in policy; and cannot create another organisation key. Everything inside a workspace is done with that workspace's own key — which this API can mint for you.

Scopes, allowlists and limits

Each organisation key carries the scopes chosen at creation: workspaces:read, workspaces:write, keys:read, keys:write, limits:read, limits:write, usage:read, members:read, members:write, audit:read. A call outside the key's scopes returns 403 insufficient_scope. A key can carry a source-IP allowlist (403 ip_not_allowed from elsewhere) and is limited to 300 requests per minute. Every change made through this API is written to the target workspace's audit log with actor_type: "system", details.via: "organisation_api" and the key id.

Get the organisation

Returns the organisation the key belongs to: its name, quota model and workspace counts. Use it to confirm which organisation a key resolves to before a deploy, the way GET /v3/whoami does for workspace keys.

GET /v3/organisation

Response (200)

{
  "id": "7c4e1a2b-0d7f-4a1e-9b3c-2f8e6d5a4c31",
  "name": "Acme Platform",
  "quota_model": "shared_pool",
  "workspaces": {
    "active": 12,
    "archived": 1
  },
  "created_at": "2026-03-02T09:12:44Z"
}

Migrating from subaccounts

The former /v3/subaccounts resource (a bare tenant record with a name and a status) was retired on 2026-10-29 and now answers 410 Gone. If you used it to label tenants, create a workspace per tenant instead: Create a workspace, then Create a workspace API key to give the tenant its own credential.

Responses

Code examples

curl https://api.wemail.io/v3/organisation \
  -H "Authorization: Bearer afn_org_…"

const res = await fetch("https://api.wemail.io/v3/organisation", {
  headers: { Authorization: "Bearer " + process.env.WEMAIL_ORG_KEY },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://api.wemail.io/v3/organisation",
    headers={"Authorization": "Bearer " + os.environ["WEMAIL_ORG_KEY"]},
)
print(res.json())

{
  "id": "7c4e1a2b-0d7f-4a1e-9b3c-2f8e6d5a4c31",
  "name": "Acme Platform",
  "quota_model": "shared_pool",
  "workspaces": {
    "active": 12,
    "archived": 1
  },
  "created_at": "2026-03-02T09:12:44Z"
}