Password Manager Integration

Overview

mailservr exposes API endpoints compatible with the SimpleLogin and Addy.io protocols. This means you can use mailservr as a forwarded email alias provider in any password manager that supports these services, including Bitwarden and 1Password.

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 mailservr account with an active plan
• At least one active domain configured
• An API key (generate one from Settings → API Keys)

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 Setup

1Password supports custom email alias providers through its SimpleLogin integration. The setup is similar to Bitwarden.

1. Open 1Password and go to Settings → Privacy
2. Under email masking, select SimpleLogin
3. Set the server URL to your mailservr instance:

   https://mailservr.app

4. Enter your mailservr API key
5. New aliases will be generated when you create logins

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 active alias limit
• Generated aliases appear in your dashboard like any other address
• Notes from the password manager (hostname, description) are saved as the alias note

Troubleshooting