Password manager integration

Overview

mailservr exposes API endpoints compatible with the request formats used by Bitwarden's SimpleLogin and Addy.io provider modes. Bitwarden supports both providers with a custom server URL. Other clients work only if they expose the same custom-provider setting.

When you create a new login in your password manager, it calls the mailservr API to generate a unique alias. The alias is created on your default domain (or a domain you specify) using your preferred email format from Settings.

Prerequisites

• A Plus, Max, or Unlimited mailservr account
• At least one active domain configured
• An API key (generate one from Settings → Developers)

Bitwarden Setup (SimpleLogin Mode)

The simplest setup uses the SimpleLogin option in Bitwarden. This requires only your API key and your mailservr instance URL.

1. Open Bitwarden and create or edit a vault entry
2. Click the Username Generator icon
3. Under Options, select Forwarded Email Alias
4. Choose SimpleLogin as the service
5. Set Server URL to your mailservr instance:

   https://mailservr.app

6. Paste your mailservr API key in the API Key field
7. Click the regenerate button to generate an alias

Bitwarden Setup (Addy.io Mode)

Alternatively, use the Addy.io option if you want to specify which domain to use for alias generation.

1. Open Bitwarden and create or edit a vault entry
2. Click the Username Generator icon
3. Under Options, select Forwarded Email Alias
4. Choose Addy.io as the service
5. Set Server URL to your mailservr instance:

   https://mailservr.app

6. Paste your mailservr API key in the API Access Token field
7. Enter your domain in the Domain Name field (e.g. yourdomain.com)
8. Click the regenerate button to generate an alias

1Password compatibility

1Password's Masked Email feature currently uses its Fastmail integration and does not expose a custom SimpleLogin or Addy.io server URL. mailservr therefore cannot be configured as a direct 1Password alias provider.

API Reference

Two endpoints are available. Both authenticate using your mailservr API key and generate aliases using your configured email format preferences.

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]"
}

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

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

Alias Generation Behavior

• Aliases are generated using your email format preference from Settings (random, first.last, random word, etc.)
• If no domain is specified, your default domain is used
• Aliases count toward your plan's total and active alias limits
• Generated aliases appear in your dashboard like any other address
• Notes from the password manager (hostname, description) are saved as the alias note

Troubleshooting