Workspaces and access

The model#

You sign in with your email, so one person can belong to several workspaces. A workspace has members, a plan, and everything you read or send: domains, inboxes, contacts, templates, campaigns, webhooks and keys. Every workspace also gets a private runearc.email domain to try things on (see Quickstart); inboxes on it are ordinary inboxes of the workspace.

An API key belongs to one workspace and can be narrowed further (below). A signed in session picks the workspace with the Runearc-Workspace header. GET /v1/me returns the signed in user, the workspace's plan, usage and counts, and your role and permissions in it; GET /v1/me/workspaces lists the workspaces you belong to.

API keys#

# A full access key
curl -X POST https://api.runearc.com/v1/keys \
  -H "Authorization: Bearer $RUNEARC_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "production" }'

# A sending key limited to one domain, and a key limited to one inbox
curl -X POST https://api.runearc.com/v1/keys -H "Authorization: Bearer $RUNEARC_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "app", "permissions": "sending", "domain_id": "dom_..." }'
curl -X POST https://api.runearc.com/v1/keys -H "Authorization: Bearer $RUNEARC_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "support bot", "permissions": "inbox", "inbox_id": "ibx_..." }'

The answer is 201 with key (id key_..., prefix, scope, permissions, last_used_at) and secret, which starts with mb_live_ and is shown once; only a hash is stored. GET /v1/keys lists keys and DELETE /v1/keys/{id} revokes one (204). Send it as Authorization: Bearer. Sending keys also work as the SMTP password; see Mail apps and forwarding.

Domain setup#

setup adds a domain and the addresses you want in one call. mode is root (receive on the domain), subdomain (receive on mail.<domain>, leaving the root's mail alone) or sending_only; each address is { "local_part", "kind": "inbox" | "sender", "display_name" }. Publish the returned records, then verify; see Domains.

Members and roles#

A member has a workspace role: owner (exactly one), admin, member or billing. Owners and admins can do everything, and billing sees billing and no mail. A member also has a member_role (admin, developer, support or viewer, default viewer) and optionally a list of inbox_ids that narrows it to those inboxes; no list means every inbox. Only owners and admins manage members.

curl -X POST https://api.runearc.com/v1/invitations \
  -H "Authorization: Bearer $RUNEARC_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "sam@acme.com", "workspace_role": "member",
        "member_role": "support", "inbox_ids": ["ibx_..."] }'

Invitations expire after 7 days. The invitee signs in with the invited address and accepts with the link; accepting needs a signed in session, not an API key.

Workspace settings, export and deletion#

GET /v1/account/export and DELETE /v1/account do the same for your own user account across workspaces. The postal address for marketing mail is GET, PUT /v1/workspace/postal-address; see Onboarding.

CLI and MCP#

runearc login
runearc whoami
runearc keys create production
runearc keys create app-inbox --inbox ibx_...
runearc keys list
runearc keys revoke key_...

Members, invitations and workspace settings have no CLI command or MCP tool; use the dashboard or the endpoints above with a session.

Errors#