MailStack/Docs
Dashboard

API Reference

Complete documentation for the MailForge REST API.

Base URL: https://api.mailstack.io/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer ms_your_api_key

Endpoints

POST/v1/email/send

Send an email. Supports template variables and scheduled delivery.

Request Body

{
  "to": "string | string[]",     // Recipient(s)
  "from": "string",              // Sender address
  "subject": "string",           // Email subject (supports {{variables}})
  "html": "string?",             // HTML body (supports {{variables}})
  "text": "string?",             // Plain text body
  "replyTo": "string?",          // Reply-to address
  "metadata": "object?",         // Custom metadata
  "variables": "object?",        // Template variables for Handlebars
  "send_at": "ISO 8601 string?"  // Schedule delivery (e.g. "2026-04-01T09:00:00Z")
}

Response

{
  "id": "em_abc123",
  "status": "queued"  // or "scheduled" or "suppressed"
}
POST/v1/email/batch

Send up to 1,000 emails in a single API call

Request Body

{
  "messages": [
    { "to": "a@example.com", "from": "...", "subject": "...", "html": "..." },
    { "to": "b@example.com", "from": "...", "subject": "...", "variables": { "name": "Bob" } }
  ]
}

Response

{
  "batchId": "batch_abc123",
  "total": 2,
  "queued": 2,
  "scheduled": 0,
  "suppressed": 0,
  "messages": [
    { "id": "em_1", "status": "queued" },
    { "id": "em_2", "status": "queued" }
  ]
}
DELETE/v1/email/:id

Cancel a scheduled or queued email

Response

{
  "id": "em_abc123",
  "status": "cancelled"
}
GET/v1/email/:id

Get email status

Response

{
  "id": "em_abc123",
  "status": "delivered",
  "from": "you@domain.com",
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "sentAt": "2026-03-27T10:00:00Z",
  "deliveredAt": "2026-03-27T10:00:02Z"
}
POST/v1/keys

Create an API key

Request Body

{
  "name": "string"  // Key name for identification
}

Response

{
  "id": "key_abc123",
  "name": "Production",
  "key": "ms_abc123...xyz",
  "prefix": "ms_abc1",
  "created_at": "2026-03-27T10:00:00Z"
}
GET/v1/analytics/summary

Get analytics summary

Response

{
  "sent": 483,
  "delivered": 460,
  "bounced": 23,
  "opened": 280
}
POST/v1/suppressions

Add emails to the suppression list

Request Body

{
  "emails": ["bounce@example.com", "spam@example.com"],
  "reason": "manual"  // "bounce" | "complaint" | "manual"
}

Response

{
  "added": 2
}
GET/v1/suppressions

List all suppressed email addresses

Response

{
  "total": 3,
  "suppressions": [
    { "email": "bounce@example.com", "reason": "bounce", "addedAt": "..." },
    { "email": "spam@example.com", "reason": "complaint", "addedAt": "..." }
  ]
}
GET/v1/suppressions/check/:email

Check if an email is suppressed

Response

{
  "email": "bounce@example.com",
  "suppressed": true,
  "reason": "bounce",
  "addedAt": "2026-03-27T10:00:00Z"
}