API Reference

Exchange email + password for a JWT access token (1 hour TTL) and an httpOnly refresh token cookie (7 days).

Request Body

POST /v1/auth/login

{
  "email": "you@company.com",
  "password": "your-password"
}

{
  "access_token": "eyJhbGci...",
  "token_type":   "Bearer",
  "expires_in":   3600
}
// + Set-Cookie: mdrt=... (httpOnly)

Issue a new access token using the httpOnly refresh token cookie. The refresh token is rotated on every call.

POST /v1/auth/refresh
// No body — uses cookie automatically

{
  "access_token": "eyJhbGci...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

Invalidates the current JWT (adds its jti to the Redis blocklist) and deletes the refresh token cookie.

{ "message": "Logged out successfully" }

List all API keys on your account. Raw key values are never returned — only metadata.

{
  "api_keys": [
    {
      "id":           "664abc...",
      "label":        "Production",
      "scope":        "send",
      "active":       true,
      "expires_at":   null,
      "last_used_at": "2025-05-01T10:22:00Z",
      "created_at":   "2025-04-01T08:00:00Z"
    }
  ],
  "total": 1
}

Create a new API key. The raw key value is returned exactly once — it is hashed and stored, so it cannot be retrieved again.

Request Body

{
  "label":           "Production",
  "scope":           "send",
  "expires_in_days": 90
}

{
  "id":         "664abc...",
  "key":        "mdsk_AbCd1234...",
  "label":      "Production",
  "scope":      "send",
  "expires_at": "2025-08-17T...",
  "_notice":    "Save this key now."
}

Revoke an API key immediately. In-flight requests using this key will fail within seconds (Redis cache invalidation).

{ "message": "API key revoked" }

Returns all sending domains on your account with their verification status.

{
  "domains": [
    {
      "_id":        "665def...",
      "domain":     "mail.yourcompany.com",
      "status":     "verified",
      "verified_at":"2025-05-10T09:00:00Z"
    }
  ],
  "total": 1
}

Add a new sending domain. Maildoot generates a 2048-bit RSA DKIM key pair and returns the full set of DNS records you need to configure.

{ "domain": "mail.yourco.com" }

{
  "domain": "mail.yourco.com",
  "status": "pending",
  "dns_records": {
    "dkim": {
      "type":  "TXT",
      "host":  "sel._domainkey.mail.yourco.com",
      "value": "v=DKIM1; k=rsa; p=MII..."
    },
    "spf": {
      "type":  "TXT",
      "host":  "mail.yourco.com",
      "value": "v=spf1 include:spf.maildoot.net ~all"
    },
    "dmarc": { ... },
    "return_path": { ... },
    "tracking": { ... }
  }
}

Triggers a live DNS lookup to check if the DKIM TXT record is correctly published. Updates the domain status to verified or failed.

{
  "domain":      "mail.yourco.com",
  "status":      "verified",
  "verified_at": "2025-05-17T11:00:00Z",
  "check": {
    "verified": true,
    "host":     "sel._domainkey.mail.yourco.com"
  }
}

Permanently removes the domain and its DKIM keys from your account.

{ "message": "Domain mail.yourco.com deleted" }

Create a new SMTP user. A random 18-character password is generated and returned once only.

{
  "username": "myapp-prod",
  "label":    "Production App"
}

{
  "id":       "abc123...",
  "username": "myapp-prod",
  "password": "Ax9#mK2!Lp3@...",
  "_notice":  "Save this password now."
}

Generates a new password and replaces the existing one. New password returned once only.

{
  "username": "myapp-prod",
  "password": "NewP@ss9#Xy...",
  "_notice":  "Save this password now."
}

Enable or disable an SMTP user without deleting it.

{ "active": false }

{ "active": false, "username": "myapp-prod" }

Register a webhook endpoint. A random HMAC secret is generated and returned once only — use it to verify incoming payloads.

{
  "url": "https://yourapp.com/hooks",
  "events": [
    "message.delivered",
    "message.bounced",
    "email.opened"
  ],
  "label": "Production Hooks"
}

{
  "id":      "667xyz...",
  "url":     "https://yourapp.com/hooks",
  "secret":  "a1b2c3d4e5f6...",
  "events":  ["message.delivered", ...],
  "status":  "active",
  "_notice": "Save this secret now."
}

Get callback detail including current health status — failure count, last response code, and last error message.

{
  "url": "https://yourapp.com/hooks",
  "health": {
    "status":            "active",
    "failure_count":     0,
    "last_triggered_at": "2025-05-17T10:30:00Z",
    "last_response_code":200,
    "last_error":        null
  }
}

Send a single email. Returns a unique msg_id (reference ID) you can use to query delivery status and reports.

Request Body

Attachment Object

POST /v1/messages

{
  "from":       "hello@acme.com",
  "from_name":  "Acme Support",
  "to":         "user@example.com",
  "cc":         ["manager@acme.com"],
  "bcc":        ["audit@acme.com"],
  "subject":    "Your invoice #1042",
  "html":       "<p>Hi, please find your invoice.</p>",
  "text":       "Hi, please find your invoice.",
  "attachments": [{
    "filename":     "invoice.pdf",
    "content":      "JVBERi0xLjQK...",
    "content_type": "application/pdf"
  }],
  "headers": {
    "X-Order-ID":    "ORD-9982",
    "X-Customer-ID": "CUST-1234"
  },
  "tracking": { "open": true, "click": true },
  "tags":        ["invoice", "billing"],
  "pool":        "transactional"
}

{
  "msg_id":     "a1b2c3d4-e5f6-...",
  "status":     "queued",
  "queued_at":  "2025-05-17T11:00:00Z"
}

// msg_id is your reference ID.
// Use it to query status via:
// GET /reports/messages/{msg_id}

// Your custom headers are echoed back
// in every webhook event payload:
{
  "event":    "message.delivered",
  "msg_id":   "a1b2c3d4...",
  "headers": {
    "X-Order-ID":    "ORD-9982",
    "X-Customer-ID": "CUST-1234"
  }
}

Fetch the full delivery record for a single message using the msg_id returned when the message was sent.

{
  "msg_id":        "a1b2c3d4-e5f6-...",
  "from":          "hello@acme.com",
  "to":            ["user@example.com"],
  "subject":       "Your invoice #1042",
  "status":        "delivered",
  "sending_ip":    "13.127.255.192",
  "pool_name":     "transactional",
  "tags":          ["invoice", "billing"],
  "queued_at":     "2025-05-17T11:00:00Z",
  "delivered_at":  "2025-05-17T11:00:03Z",
  "opened_at":     "2025-05-17T11:04:22Z",
  "clicked_at":    null,
  "bounce_code":   null,
  "bounce_reason": null,
  "retry_count":   0
}

List all templates in your account.

{
  "templates": [
    {
      "template_id": "tpl_welcome_user",
      "name":        "Welcome Email",
      "subject":     "Welcome, {{first_name}}!",
      "variables":   ["first_name", "last_name", "activation_link"],
      "created_at":  "2025-05-01T08:00:00Z",
      "updated_at":  "2025-05-10T14:30:00Z"
    }
  ],
  "total": 1
}

Create a new template. Use {{variable_name}} syntax in subject, html, and text fields. Maildoot auto-detects all variables and stores the list.

Request Body

{
  "template_id": "tpl_otp_verify",
  "name":        "OTP Verification",
  "subject":     "Your OTP is {{otp}}",
  "html": "<p>Hi {{first_name}},</p>
<p>Your one-time password is:</p>
<h2>{{otp}}</h2>
<p>Valid for {{expiry_minutes}} minutes.
Do not share it with anyone.</p>",
  "text": "Hi {{first_name}}, your OTP is {{otp}}. Valid for {{expiry_minutes}} minutes.",
  "from":        "noreply@acme.com",
  "from_name":   "Acme Security"
}

{
  "template_id": "tpl_otp_verify",
  "name":        "OTP Verification",
  "variables": [
    "first_name",
    "otp",
    "expiry_minutes"
  ],
  "created_at": "2025-05-17T11:00:00Z"
}

// Variables are auto-detected from
// {{...}} placeholders in all fields.

Fetch a single template including its full HTML/text body and detected variable list.

{
  "template_id": "tpl_otp_verify",
  "name":        "OTP Verification",
  "subject":     "Your OTP is {{otp}}",
  "html":        "<p>Hi {{first_name}}...</p>",
  "text":        "Hi {{first_name}}, your OTP...",
  "variables":   ["first_name", "otp", "expiry_minutes"],
  "from":        "noreply@acme.com",
  "from_name":   "Acme Security",
  "created_at":  "2025-05-17T11:00:00Z",
  "updated_at":  "2025-05-17T11:00:00Z"
}

Replace a template's content. All fields are optional — only provided fields are updated. The template_id itself cannot be changed.

{
  "subject": "{{first_name}}, your OTP: {{otp}}",
  "html":    "<h1>OTP: {{otp}}</h1>"
}

{
  "template_id": "tpl_otp_verify",
  "variables":   ["first_name", "otp"],
  "updated_at":  "2025-05-17T12:00:00Z"
}

Permanently delete a template. Any future send calls using this template_id will return a 404.

{ "message": "Template tpl_otp_verify deleted" }

Send an email using a saved template. Pass variables as a key-value object — every {{placeholder}} in the template is replaced before delivery. Supports all the same recipient and tracking fields as POST /messages.

Request Body

POST /v1/templates/tpl_otp_verify/send

{
  "to": "ram@example.com",
  "variables": {
    "first_name":      "Ram",
    "otp":             "847291",
    "expiry_minutes":  "10"
  },
  "headers": {
    "X-User-ID": "USR-9821"
  }
}

{
  "msg_id":       "c3d4e5f6-...",
  "template_id":  "tpl_otp_verify",
  "status":       "queued",
  "queued_at":    "2025-05-17T11:05:00Z"
}

// Subject becomes:
// "Ram, your OTP: 847291"
//
// HTML placeholder {{first_name}}
// becomes "Ram", {{otp}} becomes
// "847291", etc.

Fetch the complete delivery report for a specific transaction using the msg_id reference returned when the message was originally sent. This is the primary way to check whether a specific email was delivered, opened, clicked, or bounced.

GET /v1/reports/messages/a1b2c3d4-e5f6-...

{
  "msg_id":         "a1b2c3d4-...",
  "template_id":    "tpl_otp_verify",
  "from":           "noreply@acme.com",
  "to":             ["ram@example.com"],
  "subject":        "Ram, your OTP: 847291",
  "status":         "delivered",
  "sending_ip":     "13.127.255.192",
  "pool_name":      "transactional",
  "tags":           ["otp"],
  "retry_count":    0,
  "queued_at":      "2025-05-17T11:05:00Z",
  "delivered_at":   "2025-05-17T11:05:02Z",
  "opened_at":      "2025-05-17T11:06:14Z",
  "clicked_at":     null,
  "unsubscribed_at":null,
  "bounce_code":    null,
  "bounce_reason":  null,
  "s3_key":         "emails/usr123/a1b2c3d4.eml"
}

Aggregate delivery statistics for your account. Supports date range, domain, tag, and status filters.

Query Parameters

GET /v1/reports/summary?start_date=2025-05-01&tag=invoice

{
  "period": { "from": "2025-05-01", "to": "2025-05-17" },
  "sent":              12450,
  "delivered":        12301,
  "bounced":          82,
  "deferred":         67,
  "permanently_failed":0,
  "opened":           4820,
  "clicked":          1103,
  "unsubscribed":     14,
  "spam_complaints":  2,
  "delivery_rate":    98.8,
  "open_rate":        39.2,
  "click_rate":       8.9
}

Hourly or daily volume broken down over a date range. Use granularity=hour or granularity=day (default: day). Supports the same filters as /reports/summary.

GET /v1/reports/timeseries?granularity=day&start_date=2025-05-15

{
  "granularity": "day",
  "data": [
    {
      "period":     "2025-05-15",
      "sent":       3200,
      "delivered":  3168,
      "bounced":    22,
      "opened":     1140,
      "clicked":    290
    },
    {
      "period":     "2025-05-16",
      "sent":       4100,
      "delivered":  4055,
      "bounced":    30,
      "opened":     1560,
      "clicked":    401
    }
  ]
}