API Reference

Authentication

All API requests require authentication via an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Generate API keys from Settings → API Keys in the dashboard. Pro plans include 1 key, Enterprise plans include up to 10.

All responses follow the shape { data: T } on success or { error: string } on failure.

Addresses

Create, list, update, and delete email aliases.

Example: Create address

curl -X POST https://mailservr.app/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "notifications", "domainId": 1, "note": "GitHub alerts"}'

// Response (201):
{
  "data": {
    "id": 42,
    "name": "notifications",
    "enabled": true,
    "note": "GitHub alerts",
    "expiresAt": null,
    "domain": { "id": 1, "name": "priv.sh", "receiveOnly": false }
  }
}

Example: Generate random address

curl -X POST https://mailservr.app/api/addresses/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domainId": 1}'

// Response (201):
{
  "data": {
    "id": 43,
    "name": "sarah.mitchell42",
    "enabled": true,
    "domain": { "id": 1, "name": "priv.sh", "receiveOnly": false }
  }
}

Address Categories

Organize addresses into color-coded categories.

Example: Create category

curl -X POST https://mailservr.app/api/address-categories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work", "color": "#3B82F6"}'

// Response (201):
{
  "data": {
    "id": 5,
    "name": "Work",
    "color": "#3B82F6",
    "sortOrder": 0
  }
}

Emails

Read, compose, reply, and manage email threads.

Example: List threads

curl "https://mailservr.app/api/emails?folder=inbox&limit=10&search=deploy" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Response:
{
  "data": {
    "items": [
      {
        "id": 87,
        "subject": "Deployment successful",
        "snippet": "Your app was deployed to...",
        "isRead": false,
        "isStarred": false,
        "lastMessageAt": "2026-02-13T10:30:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
  }
}

Example: Compose email

curl -X POST https://mailservr.app/api/emails/compose \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addressId": 42,
    "to": "[email protected]",
    "subject": "Hello from mailservr",
    "textBody": "This is a test email."
  }'

// Response (201):
{
  "data": {
    "id": 88,
    "subject": "Hello from mailservr",
    "emails": [{ "id": 150, "from": "[email protected]", "status": "SENT" }]
  }
}

Query parameters for GET /api/emails

Domains

List available domains. Domain creation is admin-restricted.

Example: List domains

curl https://mailservr.app/api/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

// Response:
{
  "data": [
    {
      "id": 1,
      "name": "priv.sh",
      "status": "ACTIVE",
      "isPrivate": false,
      "receiveOnly": false,
      "_count": { "addresses": 12 }
    }
  ]
}

Blocked Senders

Block specific senders from delivering to your addresses.

Example: Block a sender

curl -X POST https://mailservr.app/api/blocked-senders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addressId": 42, "senderEmail": "[email protected]"}'

// Response (201):
{
  "data": {
    "id": 7,
    "addressId": 42,
    "senderEmail": "[email protected]",
    "createdAt": "2026-02-13T10:30:00Z"
  }
}

API Keys

Manage API keys for programmatic access.

Example: Create API key

curl -X POST https://mailservr.app/api/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "expiresAt": "2027-01-01T00:00:00Z"}'

// Response (201):
{
  "data": {
    "id": 3,
    "name": "CI/CD Pipeline",
    "keyPrefix": "ms_abc1",
    "expiresAt": "2027-01-01T00:00:00Z",
    "key": "ms_abc123def456..."
  }
}

The full key value is only returned once at creation time. Store it securely.

Webhooks

Manage outbound webhook endpoints. Available on the Enterprise plan. See the webhook documentation for event payloads and signature verification.

Example: Create webhook

curl -X POST https://mailservr.app/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["EMAIL_RECEIVED", "THREAD_CREATED"]
  }'

// Response (201):
{
  "data": {
    "id": 2,
    "url": "https://example.com/webhook",
    "events": ["EMAIL_RECEIVED", "THREAD_CREATED"],
    "enabled": true,
    "secret": "whsec_abc123..."
  }
}

The secret is only returned once at creation time. Use it to verify webhook signatures.

Push Notifications

Subscribe to browser push notifications for new emails.

Example: Subscribe

curl -X POST https://mailservr.app/api/push/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "keys": {
      "p256dh": "BNcRd...",
      "auth": "tBHI..."
    }
  }'

// Response:
{ "data": { "id": 12 } }

Attachments

Download email attachments via presigned URLs.

Example

curl https://mailservr.app/api/attachments/15 \
  -H "Authorization: Bearer YOUR_API_KEY"

// Response:
{
  "data": {
    "url": "https://storage.example.com/...",
    "filename": "report.pdf",
    "contentType": "application/pdf"
  }
}

Preferences

Manage user preferences for default domain and alias generation format.

Example: Update preferences

curl -X PATCH https://mailservr.app/api/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"defaultDomainId": 1, "emailFormat": "FIRST_DOT_LAST", "includeNumbers": true}'

// Response:
{
  "data": {
    "defaultDomainId": 1,
    "emailFormat": "FIRST_DOT_LAST",
    "includeNumbers": true,
    "defaultDomain": { "id": 1, "name": "priv.sh" }
  }
}

Email format options

Password Manager Aliases

SimpleLogin and Addy.io-compatible endpoints for password manager integration. See the password manager setup guide for configuration instructions.

Example: SimpleLogin

curl -X POST "https://mailservr.app/api/alias/random/new?hostname=github.com" \
  -H "Authentication: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Generated for github.com"}'

// Response (201):
{ "alias": "[email protected]" }

Example: Addy.io

curl -X POST https://mailservr.app/api/v1/aliases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "priv.sh", "description": "Generated for github.com"}'

// Response (201):
{ "data": { "email": "[email protected]" } }