API reference

Authentication

Authenticated user-resource endpoints accept an API key passed as a Bearer token in the Authorization header. Dashboard requests may use the signed-in session cookie; public configuration and signed webhook routes document their own authentication.

Authorization: Bearer YOUR_API_KEY

Generate API keys from Settings → Developers in the dashboard. Plus includes 1 key; Max includes up to 10.

REST responses follow { data: T } on success or { error: string } on failure. The SimpleLogin compatibility endpoint intentionally uses its provider-specific top-level shape.

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",
        "messageCount": 1,
        "isRead": false,
        "isStarred": false,
        "lastMessageAt": "2026-02-13T10:30:00Z",
        "emails": [
          {
            "id": 150,
            "snippet": "Your app was deployed to...",
            "fromAddress": "[email protected]",
            "fromName": "Build system"
          }
        ]
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
  }
}

Example: Compose email

Send a unique `Idempotency-Key` header and reuse it only when retrying the exact same compose, reply, or scheduling request. A key reused with different content returns 409.

curl -X POST https://mailservr.app/api/emails/compose \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8449af57-b9cf-4d5b-a12e-6b605e58e6bf" \
  -d '{
    "addressId": 42,
    "to": "[email protected]",
    "subject": "Hello from mailservr",
    "textBody": "Hello from mailservr."
  }'

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

Schedule delivery

Add a future ISO-8601 `scheduledAt` value to compose or reply. Delivery rechecks the current plan and sending limits, and pending messages can be canceled through the scheduled endpoint.

curl -X POST https://mailservr.app/api/emails/compose \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: e8a9a9f0-97b2-4c7e-a672-9108dcf58acb" \
  -d '{
    "addressId": 42,
    "to": "[email protected]",
    "subject": "A note for tomorrow",
    "textBody": "See you then.",
    "scheduledAt": "2026-08-01T09:00:00.000Z"
  }'

Query parameters for GET /api/emails

Free accounts receive their visible 7-day history only; retained older messages are restored automatically after an upgrade.

Domains

List available domains. Domain creation is admin-restricted; address counts on shared domains are scoped to the current user unless the caller is an administrator.

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": "a3f95c10",
    "expiresAt": "2027-01-01T00:00:00Z",
    "key": "a3f95c10d42e7b8f4e38ce758ea3d907f946b5991768bf47c314f4892b107f65"
  }
}

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

Webhooks

Manage outbound webhook endpoints. Available on the Max 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",
    "format": "STANDARD",
    "events": ["EMAIL_RECEIVED", "THREAD_CREATED"]
  }'

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

The secret is only returned once for STANDARD endpoints. Set format to DISCORD for a direct Discord incoming webhook URL; Discord endpoints return no secret and receive embed payloads.

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/...",
    "expiresAt": "2026-07-17T10:15:00.000Z",
    "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

Endpoints matching the SimpleLogin and Addy.io request formats used by Bitwarden's custom-server provider modes. 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]" } }