White-Label Email Architecture

Ark is built around a four-level hierarchy: Platform → Tenant → Domain → Email. This architecture lets your SaaS platform give each customer their own sending domains and independent configuration — without building email infrastructure from scratch.

Hierarchy

Level	What It Represents	Example
Platform	Your Ark account. The top-level container for all resources.	Your SaaS company
Tenant	One of your customers. Gets isolated domains, credentials, webhooks, suppressions, and usage tracking.	”Acme Corp” — a customer of your platform
Domain	A sending domain belonging to a tenant. Configured with , , and .	`acme.com` or `mail.acme.com`
Email	A single email sent from a verified domain.	Welcome email from `hello@acme.com`

When to Use Tenants

Use tenants whenever your platform sends email on behalf of distinct customers or organizational units:

SaaS platforms — each customer sends from their own domain (@customer.com)
Agencies — each client has separate sending domains and deliverability
Marketplaces — sellers send order confirmations from their brand
Internal teams — departments with separate sending requirements

If you’re building a single product that sends email from one domain, you can use the default tenant that comes with your account. Tenants become essential when you need per-customer isolation.

Creating a Tenant

Python
Node.js
Ruby
Go
cURL

from ark import Ark

client = Ark()

tenant = client.tenants.create(
    name="Acme Corp",
    metadata={"plan": "enterprise", "customer_id": "cust_123"}
)

print(f"Tenant created: {tenant.data.id}")

import Ark from 'ark-email';

const client = new Ark();

const tenant = await client.tenants.create({
  name: 'Acme Corp',
  metadata: { plan: 'enterprise', customer_id: 'cust_123' },
});

console.log(`Tenant created: ${tenant.data.id}`);

require "ark_email"

client = ArkEmail::Client.new

tenant = client.tenants.create(
  name: "Acme Corp",
  metadata: { plan: "enterprise", customer_id: "cust_123" }
)

puts "Tenant created: #{tenant.data.id}"

client := ark.NewClient()

tenant, err := client.Tenants.Create(ctx, ark.TenantCreateParams{
    Name:     ark.String("Acme Corp"),
    Metadata: map[string]string{"plan": "enterprise", "customer_id": "cust_123"},
})

fmt.Printf("Tenant created: %s\n", tenant.Data.ID)

curl -X POST https://api.arkhq.io/v1/tenants \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "metadata": {"plan": "enterprise", "customer_id": "cust_123"}
  }'

Isolation Model

Each tenant is fully isolated. Nothing leaks between tenants:

Resource	Isolation
Domains	Each tenant has its own verified sending domains
Reputation	Sending reputation is per-domain. One tenant’s bad practices don’t affect another.
Credentials	Per-tenant API keys and SMTP credentials
Webhooks	Each tenant can have its own webhook endpoints and subscribed events
Suppressions	Bounce and complaint suppressions are tenant-scoped
Usage	Email volume and analytics tracked independently per tenant

Per-tenant domains are the key benefit. Each customer sends from their own authenticated domains with full DKIM, SPF, and DMARC configuration.

Sending as a Tenant

Once a tenant has a verified domain, send email on their behalf using tenant-scoped credentials:

Python
Node.js
Ruby
Go

from ark import Ark

# Use tenant-scoped credentials
client = Ark(api_key="ark_live_tenant_...")

email = client.emails.send(
    from_="hello@acme.com",
    to=["user@example.com"],
    subject="Welcome to Acme",
    html="<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    metadata={"user_id": "usr_456"}
)

import Ark from 'ark-email';

// Use tenant-scoped credentials
const client = new Ark({ apiKey: 'ark_live_tenant_...' });

const email = await client.emails.send({
  from: 'hello@acme.com',
  to: ['user@example.com'],
  subject: 'Welcome to Acme',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  metadata: { user_id: 'usr_456' },
});

require "ark_email"

# Use tenant-scoped credentials
client = ArkEmail::Client.new(api_key: "ark_live_tenant_...")

email = client.emails.send_(
  from: "hello@acme.com",
  to: ["user@example.com"],
  subject: "Welcome to Acme",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  metadata: { user_id: "usr_456" }
)

// Use tenant-scoped credentials
client := ark.NewClient(ark.WithAPIKey("ark_live_tenant_..."))

email, _ := client.Emails.Send(ctx, ark.EmailSendParams{
    From:     "hello@acme.com",
    To:       []string{"user@example.com"},
    Subject:  "Welcome to Acme",
    HTML:     ark.String("<h1>Welcome!</h1><p>Thanks for signing up.</p>"),
    Metadata: map[string]string{"user_id": "usr_456"},
})

Per-Tenant Analytics

Track sending volume, deliverability, and engagement per tenant:

Python
Node.js
cURL

# Get usage for a specific tenant
usage = client.tenants.usage.retrieve("tenant_abc123")

print(f"Emails sent: {usage.data.emails_sent}")
print(f"Bounces: {usage.data.bounces}")
print(f"Complaints: {usage.data.complaints}")

# Get usage timeseries
timeseries = client.tenants.usage.timeseries("tenant_abc123")
for point in timeseries.data:
    print(f"{point.date}: {point.emails_sent} sent")

// Get usage for a specific tenant
const usage = await client.tenants.usage.retrieve('tenant_abc123');

console.log(`Emails sent: ${usage.data.emailsSent}`);
console.log(`Bounces: ${usage.data.bounces}`);

// Get usage timeseries
const timeseries = await client.tenants.usage.timeseries('tenant_abc123');
for (const point of timeseries.data) {
  console.log(`${point.date}: ${point.emailsSent} sent`);
}

# Get usage for a specific tenant
curl https://api.arkhq.io/v1/tenants/tenant_abc123/usage \
  -H "Authorization: Bearer $ARK_API_KEY"

# Get usage timeseries
curl https://api.arkhq.io/v1/tenants/tenant_abc123/usage/timeseries \
  -H "Authorization: Bearer $ARK_API_KEY"

Next Steps

Tenant Management

Full CRUD operations for tenants, credentials, and configuration

Domain Onboarding

Build domain setup flows for your customers

Domain Setup

Configure DKIM, SPF, and DMARC for sending domains

Sending Email

Send transactional email via API or SMTP

Getting Started

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

White-Label Email Architecture — Platform, Tenant & Domain Hierarchy

Hierarchy

When to Use Tenants

Creating a Tenant

Isolation Model

Sending as a Tenant

Per-Tenant Analytics

Next Steps

Tenant Management

Domain Onboarding

Domain Setup

Sending Email

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

​Hierarchy

​When to Use Tenants

​Creating a Tenant

​Isolation Model

​Sending as a Tenant

​Per-Tenant Analytics

​Next Steps

Tenant Management

Domain Onboarding

Domain Setup

Sending Email

Hierarchy

When to Use Tenants

Creating a Tenant

Isolation Model

Sending as a Tenant

Per-Tenant Analytics

Next Steps