Agency Feature

Workspaces for Agencies

Manage multiple clients from a single account. Workspaces provide complete data isolation, scoped API access, and per-client analytics.

How Workspaces Work

Create Workspaces

Create a workspace for each client. Give it a name, optional industry tag, and you're ready to go.

Assign Resources

Subscribers, campaigns, domains, and templates are automatically scoped to the active workspace.

Switch & Manage

Use the workspace switcher to jump between clients, or view "All Workspaces" for aggregated data.

Using Workspaces in Dashboard

Workspace Switcher

Find the workspace switcher in the sidebar (desktop) or header (mobile). Click to see all your workspaces.

•All Workspaces - View aggregated data across all clients
•Select a workspace - Filter everything to that client only
•Create Workspace - Add a new client workspace

What Gets Filtered

When you select a workspace, these areas automatically filter to show only that client's data:

Subscribers

Campaigns

Templates

Domains

Workflows

Analytics

API Keys

Webhooks

Pixels

API Integration

Two ways to work with workspaces via API: scoped API keys or workspace headers.

1Workspace-Scoped API Keys (Recommended)

Create an API key tied to a specific workspace. All requests using this key automatically access only that workspace's data.

bash

curl -X POST https://sendmailos.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Integration Key",
    "workspace_id": "ws_abc123...",
    "scopes": ["subscribers:read", "subscribers:write"]
  }'

Best for client integrations

Share workspace-scoped keys with clients safely. They can only access their own data.

2X-Workspace-Id Header

Use an organization-level API key and specify the workspace per request.

bash

curl -X POST https://sendmailos.com/api/v1/subscribers \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Workspace-Id: ws_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "tags": ["newsletter"]
  }'

3Master API Key (Recommended for SaaS Platforms)

Master keys access all workspaces with a single key. Create workspaces programmatically with full control over settings.

javascript

import { SendMailOS } from '@sendmailos/sdk';

// Master key - access all workspaces
const platform = new SendMailOS('sk_live_master_key...');

// 1. Create workspace first (industry is optional)
const { workspace } = await platform.workspaces.create({
  name: 'Pizza Palace',
  industry: 'restaurants',  // optional - can be null
  website: 'https://pizzapalace.com'
});

// 2. Add domain TO that workspace
const { dns_records } = await platform.domains.create({
  domain: 'pizzapalace.com',
  workspaceId: workspace.id
});

// 3. After DNS verified, send emails
await platform.emails.send({
  to: '[email protected]',
  fromEmail: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1>',
  workspaceId: workspace.id
});

Workspace-first flow recommended

Create workspace first (industry is optional), then add domain. This gives you full control over workspace settings before the client verifies their domain.

SDK Usage

javascript

import { SendMailOS } from '@sendmailos/sdk';

// Initialize with workspace-scoped API key
const acmeClient = new SendMailOS('sk_live_acme_key...');

// All operations are automatically scoped to Acme workspace
await acmeClient.subscribers.create({
  email: '[email protected]',
  first_name: 'John'
});

// Or use organization key with workspace header
const orgClient = new SendMailOS('sk_live_org_key...', {
  workspaceId: 'ws_abc123...'
});

Workspace Webhooks

Webhooks can be scoped to specific workspaces. Events include workspace context for routing.

When you create a webhook while a workspace is selected, it only receives events for that workspace. Organization-wide webhooks receive all events with workspace_id included.

json

// Webhook payload includes workspace context
{
  "event": "subscriber.created",
  "workspace_id": "ws_abc123...",
  "workspace_name": "Acme Corp",
  "data": {
    "id": "sub_xyz...",
    "email": "[email protected]",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Workspace Capabilities

Everything you need to manage clients at scale.

Client Isolation

Each workspace keeps client data completely separate - subscribers, campaigns, and analytics stay isolated.

Scoped API Keys

Create API keys that only access specific workspace data. Perfect for client integrations.

Workspace Webhooks

Route webhook events to different endpoints per client for custom integrations.

Per-Client Analytics

View stats and reports filtered by workspace. Easy client reporting.

Access Control

Invite clients with limited access to view their own reports and data.

Unified Management

Switch between workspaces instantly or view aggregated data across all clients.

Best Practices

Use descriptive workspace names

Name workspaces after your clients (e.g., "Acme Corp", "TechStart Inc") for easy identification.

Create separate domains per workspace

Each client should have their own verified sending domain for best deliverability and brand consistency.

Use workspace-scoped API keys for client integrations

Never share organization-level keys. Create scoped keys with minimum required permissions.

Set up per-workspace webhooks for custom integrations

Route events to different endpoints if clients have their own systems to integrate with.

Get Started with Workspaces

Create your first client workspace and start organizing your agency's email operations.

Create Workspace Learn About API Keys