SendStack Documentation

Dashboard Access

Sign in at /login with your configured email and password. Sessions last 30 days via a signed, httpOnly cookie.

This is a single-user application — the login credentials are set via environment variables (SINGLE_USER_EMAIL and SINGLE_USER_PASSWORD).

API Authentication

All requests to /api/send must include a server key in the x-sendstack-server-key header.

There are two types of server keys:

Creating a Project

In the dashboard, go to Projects and enter a name (2–80 characters). A unique server key is generated automatically.

POST /api/projects
Content-Type: application/json
Cookie: sendstack_session=...

{ "name": "My SaaS App" }

→ 201 { "project": { "id": "...", "name": "My SaaS App", "serverKey": "sk_..." } }

Managing API Keys

Each project has a unique server key visible on the Projects page. You can:

• Copy — click the copy icon to copy the full key to your clipboard
• Rotate — click the rotate icon to generate a new key. The old key stops working immediately.

POST /api/projects/:projectId/rotate-key
Cookie: sendstack_session=...

→ 200 { "serverKey": "sk_new_key_here" }

Supported Providers

You can mix providers across domains within the same project — for example, use SES for your main app and Resend for onboarding emails. SendStack routes automatically based on the domain in each send request.

Adding a Domain

In the dashboard, click Add Domain on the Domains page and fill in:

• Project — which project this domain belongs to
• Domain name — e.g. mail.example.com
• Provider — SES, SendGrid, Mailgun, or Resend
• Credentials — your provider API keys (encrypted before storage)
• Webhook URL (optional) — where to forward normalized provider events

Verifying a Domain

After adding a domain, click Verify to check your DNS configuration. SendStack checks:

Amazon SES

Amazon Simple Email Service offers the lowest per-email cost and is ideal for high-volume transactional email.

1. Get Your Credentials

• Open the IAM Console in AWS and create a new IAM user (or use an existing one) with the AmazonSESFullAccess policy attached.
• Generate an Access Key for the user. Save the Access Key ID and Secret Access Key — you won't be able to see the secret again.
• Note your SES Region (e.g. us-east-1, eu-west-1). This must match the region where your domain is verified in SES.

2. Verify Your Domain in SES

• In the SES Console, go to Verified Identities → Create Identity → select Domain.
• Enter your domain (e.g. mail.example.com) and follow the instructions to add DKIM CNAME records to your DNS.
• Note the DKIM Selector (usually a hash like abcdef1234) — you'll need this in SendStack.

3. Move Out of Sandbox

New SES accounts start in sandbox mode, which only allows sending to verified email addresses. To send to any recipient:

• Go to SES Console → Account Dashboard → Request Production Access.
• Fill in your use case (transactional email) and expected volume. Approval usually takes 24 hours.

SendStack detects sandbox mode during domain verification and deducts 20 points from your health score until resolved.

4. Configure in SendStack

{
  "region": "us-east-1",
  "accessKeyId": "AKIA...",
  "secretAccessKey": "wJal...",
  "fromEmail": "noreply@mail.example.com",
  "dkimSelector": "selector1"
}

5. Set Up Webhooks

• In the SES Console, go to Configuration Sets → create a new set or use an existing one.
• Add an SNS Destination for each event type you want to track (Send, Delivery, Bounce, Complaint, Open, Click).
• Create an SNS Topic and add an HTTPS Subscription pointing to:
  https://your-instance.com/api/webhooks/ses
• SNS will send a confirmation request — SendStack automatically confirms it.

SendGrid

SendGrid (by Twilio) offers a generous free tier and straightforward API key setup.

1. Get Your API Key

• Log in to your SendGrid Dashboard → Settings → API Keys.
• Click Create API Key → select Restricted Access → enable Mail Send permission.
• Copy the generated key (starts with SG.) — it's only shown once.

2. Authenticate Your Domain

• Go to Settings → Sender Authentication → Authenticate Your Domain.
• Follow the wizard to add the required CNAME records to your DNS for DKIM and SPF authentication.
• SendGrid will verify the records automatically once they propagate.

3. Configure in SendStack

{
  "apiKey": "SG.xxxxx...",
  "fromEmail": "noreply@mail.example.com"
}

4. Set Up Webhooks

• Go to Settings → Mail Settings → Event Webhook.
• Set the HTTP Post URL to:
  https://your-instance.com/api/webhooks/sendgrid
• Select the events you want to receive: Processed, Delivered, Bounce, Spam Report, Open, Click.
• Enable Signed Event Webhook and copy the Verification Key — set it as your SENDGRID_WEBHOOK_PUBLIC_KEY environment variable.

Mailgun

Mailgun is developer-focused with strong deliverability and a flexible API.

1. Get Your API Key

• Log in to your Mailgun Dashboard → click your profile → API Security.
• Copy your Private API Key (starts with key-).

2. Add and Verify Your Domain

• Go to Sending → Domains → Add New Domain.
• Enter your sending domain (e.g. mg.example.com) — Mailgun recommends using a subdomain.
• Add the DNS records Mailgun provides: SPF TXT record, DKIM TXT records, and MX records.
• Click Verify DNS Settings to confirm.

3. Configure in SendStack

{
  "apiKey": "key-xxxxx...",
  "sendingDomain": "mg.example.com",
  "fromEmail": "noreply@mg.example.com"
}

The sendingDomain should match the domain you verified in Mailgun (typically the subdomain).

4. Set Up Webhooks

• Go to Sending → Webhooks → select your domain.
• Click Add Webhook for each event type and set the URL to:
  https://your-instance.com/api/webhooks/mailgun
• Copy your Webhook Signing Key from the webhook settings page and set it as your MAILGUN_WEBHOOK_SIGNING_KEY environment variable.

Resend

Resend is a modern email API built for developers, with a clean interface and simple integration.

1. Get Your API Key

• Sign up or log in at resend.com → go to API Keys in the sidebar.
• Click Create API Key → give it a name and select Sending access permission.
• Optionally restrict the key to a specific domain for extra security.
• Copy the generated key (starts with re_) — it's only shown once.

2. Add and Verify Your Domain

• Go to Domains in the Resend dashboard → click Add Domain.
• Enter your domain (e.g. mail.example.com).
• Resend provides DNS records to add: SPF TXT record, DKIM CNAME records, and optionally a DMARC record.
• Add all records to your DNS provider and click Verify. Propagation usually takes a few minutes.

3. Configure in SendStack

{
  "apiKey": "re_xxxxx...",
  "fromEmail": "noreply@mail.example.com"
}

The fromEmail must use a domain you've verified in Resend.

4. Set Up Webhooks

• Go to Webhooks in the Resend dashboard → click Add Webhook.
• Set the Endpoint URL to:
  https://your-instance.com/api/webhooks/resend
• Select the events to subscribe to: email.sent, email.delivered, email.bounced, email.complained, email.opened, email.clicked.
• After creating the webhook, copy the Signing Secret (starts with whsec_) and set it as your RESEND_WEBHOOK_SIGNING_SECRET environment variable.

Switching Providers

SendStack makes it straightforward to switch providers or run multiple providers in parallel:

• Per-domain routing — each domain is tied to one provider. Add a new domain with a different provider to start using it alongside existing domains.
• No code changes — your API calls use the domain field to route. Change which domain you send through, and SendStack handles the rest.
• Gradual migration — run both providers simultaneously during migration. Route new traffic to the new domain while the old one continues to work.

{
  "project_id": "proj_123",
  "domain": "mail.example.com",
  "to": "user@example.com",
  "subject": "Hello",
  "html": "<p>Sent via SES</p>"
}

{
  "project_id": "proj_123",
  "domain": "notifications.example.com",
  "to": "user@example.com",
  "subject": "Hello",
  "html": "<p>Sent via Resend</p>"
}

Provider Comparison

Send Endpoint

You can send with inline content (subject + html) or use a saved template (template_id + variables). The two modes are mutually exclusive.

POST /api/send
Content-Type: application/json
x-sendstack-server-key: sk_your_key_here

{
  "project_id": "clxyz...",
  "domain": "mail.example.com",
  "to": "recipient@example.com",
  "subject": "Order Confirmation #1234",
  "html": "<h1>Thanks for your order!</h1><p>Details below...</p>",
  "text": "Thanks for your order! Details below...",
  "from_name": "Acme Store",
  "reply_to": "support@acme.com",
  "metadata": { "order_id": "1234" }
}

POST /api/send
Content-Type: application/json
x-sendstack-server-key: sk_your_key_here

{
  "project_id": "clxyz...",
  "domain": "mail.example.com",
  "to": "recipient@example.com",
  "template_id": "cltemplate123...",
  "variables": {
    "name": "Jane",
    "order_id": "1234"
  }
}

Request Fields

Response

{
  "message_id": "provider-generated-id",
  "provider": "SES",
  "accepted": true,
  "request_id": "uuid-for-tracing"
}

Code Examples

async function sendEmail({ to, subject, html }) {
  const res = await fetch(process.env.SENDSTACK_API_BASE + "/api/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-sendstack-server-key": process.env.SENDSTACK_SERVER_KEY,
    },
    body: JSON.stringify({
      project_id: process.env.SENDSTACK_PROJECT_ID,
      domain: "mail.example.com",
      to,
      subject,
      html,
    }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }

  return res.json();
}

import requests, os

def send_email(to, subject, html):
    res = requests.post(
        f"{os.environ['SENDSTACK_API_BASE']}/api/send",
        headers={
            "Content-Type": "application/json",
            "x-sendstack-server-key": os.environ["SENDSTACK_SERVER_KEY"],
        },
        json={
            "project_id": os.environ["SENDSTACK_PROJECT_ID"],
            "domain": "mail.example.com",
            "to": to,
            "subject": subject,
            "html": html,
        },
    )
    res.raise_for_status()
    return res.json()

What Happens When You Send

Creating a Template

Use the Templates page in the dashboard, or the API:

POST /api/templates
Content-Type: application/json
Cookie: sendstack_session=...

{
  "projectId": "clxyz...",
  "name": "welcome-email",
  "subject": "Welcome, {{name}}!",
  "html": "<h1>Hi {{name}}</h1><p>Thanks for joining {{company}}.</p>",
  "variables": ["name", "company"]
}

Template names must be unique within a project. The variables array documents expected placeholders but is not enforced — the actual interpolation validates at send time.

Variable Interpolation

Variables use double-brace syntax: {{variable_name}}. When you send an email using template_id, all placeholders in the subject and HTML body are replaced with the values from variables.

// Template: "Hello {{name}}, your order #{{order_id}} is confirmed."
// Variables: { "name": "Jane", "order_id": "5678" }
// Result:   "Hello Jane, your order #5678 is confirmed."

Managing Templates

Batch Endpoint

POST /api/send/batch
Content-Type: application/json
x-sendstack-server-key: sk_your_key_here

{
  "project_id": "clxyz...",
  "domain": "mail.example.com",
  "template_id": "cltemplate123...",
  "from_name": "Acme Store",
  "recipients": [
    {
      "to": "jane@example.com",
      "variables": { "name": "Jane", "code": "WELCOME10" }
    },
    {
      "to": "bob@example.com",
      "variables": { "name": "Bob", "code": "WELCOME20" },
      "from_name": "Bob's Personal Rep"
    }
  ]
}

Batch Request Fields

Each recipient object can override subject, html, text, from_name, reply_to, and provide unique variables and metadata.

Batch Response

{
  "results": [
    { "to": "jane@example.com", "message_id": "abc...", "accepted": true },
    { "to": "bob@example.com", "error": "suppressed (bounce)", "suppressed": true }
  ],
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "request_id": "req_..."
}

The batch endpoint never fails entirely — individual recipients may succeed or fail independently. Suppressed recipients are marked with suppressed: true.

Automatic Suppression

When SendStack receives a bounce or complaint webhook event from your provider, the recipient email is automatically added to the project's suppression list. This protects your sender reputation.

Managing Suppressions

Use the Suppressions page in the dashboard, or the API:

POST /api/suppressions
Cookie: sendstack_session=...

{ "projectId": "clxyz...", "email": "user@example.com", "reason": "MANUAL" }

DELETE /api/suppressions/:id
Cookie: sendstack_session=...

Removing a suppression allows future sends to that address. The suppression list is searchable and paginated in the dashboard.

Webhook Endpoint

Point your provider's webhook settings to:

https://your-instance.com/api/webhooks/ses
https://your-instance.com/api/webhooks/sendgrid
https://your-instance.com/api/webhooks/mailgun
https://your-instance.com/api/webhooks/resend

Event Types

Inbound Signature Verification

Each provider's webhooks are verified using their native signature mechanism:

• SES: SNS certificate-based RSA-SHA1 signature verification
• SendGrid: ECDSA signature via x-twilio-email-event-webhook-signature header (requires SENDGRID_WEBHOOK_PUBLIC_KEY env var)
• Mailgun: HMAC-SHA256 signature verification (requires MAILGUN_WEBHOOK_SIGNING_KEY env var)
• Resend: Svix HMAC-SHA256 signature verification via svix-signature header (requires RESEND_WEBHOOK_SIGNING_SECRET env var)

An optional shared secret (PROVIDER_WEBHOOK_SHARED_SECRET) can be used as a fallback for any provider.

Webhook Forwarding

If you configured a Webhook URL on your domain, SendStack forwards normalized events to your endpoint. Events are delivered with up to 3 retry attempts using exponential backoff (200ms, 800ms, 3.2s).

Each delivery includes these headers:

Outbound Signature Verification

Verify the authenticity of forwarded webhooks using HMAC-SHA256:

import crypto from "crypto";

function verifyWebhook(body, timestamp, signature, secret) {
  const data = timestamp + "." + body;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(data)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const body = await req.text();
const timestamp = req.headers.get("x-sendstack-timestamp");
const signature = req.headers.get("x-sendstack-signature");

if (!verifyWebhook(body, timestamp, signature, WEBHOOK_SECRET)) {
  return new Response("Invalid signature", { status: 401 });
}

Set the signing secret via the WEBHOOK_SIGNING_SECRET environment variable. If not set, it falls back to ENCRYPTION_KEY.

Health Score Calculation

score = 100
score -= bounceRate × 220
score -= complaintRate × 420
score -= (no DKIM) ? 15 : 0
score -= (no DMARC) ? 12 : 0
score -= (webhook inactive) ? 8 : 0
score -= (SES sandbox) ? 20 : 0

Final score: clamped to 0–100

Daily Aggregation

A daily cron job (4 AM UTC) aggregates webhook events by domain and date. It computes delivery, bounce, complaint, open, and click counts, then updates each domain's health score. Events older than 90 days are automatically pruned.

Environment Variables

# Database (PostgreSQL)
DATABASE_URL=postgresql://user:pass@host:5432/sendstack

# Encryption (32-byte hex string for AES-256-GCM)
ENCRYPTION_KEY=your-64-char-hex-string

# Session signing (32+ random characters)
APP_SESSION_SECRET=your-random-session-secret

# Single-user login credentials
SINGLE_USER_EMAIL=you@example.com
SINGLE_USER_PASSWORD=your-strong-password

# Global API key (fallback for all projects)
SENDSTACK_SERVER_KEY=your-global-api-key

# Cron job authorization
CRON_SECRET=your-cron-secret

# Public URL of your instance
NEXT_PUBLIC_APP_URL=https://your-domain.com

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_SUCCESS_URL=https://your-domain.com/billing?success=1
STRIPE_CANCEL_URL=https://your-domain.com/billing?canceled=1

# Shared secret for all providers (fallback)
PROVIDER_WEBHOOK_SHARED_SECRET=your-shared-secret

# SendGrid-specific
SENDGRID_WEBHOOK_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...

# Mailgun-specific
MAILGUN_WEBHOOK_SIGNING_KEY=your-mailgun-key

# Resend-specific
RESEND_WEBHOOK_SIGNING_SECRET=whsec_your-resend-secret

# HMAC-SHA256 key for signing forwarded webhooks (min 32 chars)
# Falls back to ENCRYPTION_KEY if not set
WEBHOOK_SIGNING_SECRET=your-64-char-hex-string

Generating Secrets

# 32-byte hex encryption key
openssl rand -hex 32

# Session secret
openssl rand -base64 32

# Server key
openssl rand -base64 24 | tr '+/' '-_' | sed 's/=//g' | sed 's/^/sk_/'

# Cron secret
openssl rand -base64 16

Deploying

# 1. Clone the repository
git clone https://github.com/apwn/sendstack.git
cd sendstack

# 2. Install dependencies
npm install

# 3. Set up your .env file with all required variables

# 4. Push the database schema
npx prisma db push

# 5. Deploy to Vercel
vercel --prod

The vercel.json file includes a cron configuration that runs the daily aggregation job at 4 AM UTC automatically.

Authentication

Send Email

Templates

Suppressions

Projects

Domains

Webhooks

Billing

Other

Common Headers