Skip to main content

Authentication

All requests to the mail2many API must be authenticated with an API key. An API key is always linked to exactly one mail2many account and provides access only to that account.

API key​

Users can generate and manage multiple API keys in their mail2many account. Each API key can have different permissions.

Since an API key grants access to a mail2many account, it should be treated like a password. External applications should always store API keys securely and make sure they are not visible to anyone.

For more information about API keys, management, and permissions, see the API Keys documentation.

HTTP Basic Authentication​

To send a request, use HTTP Basic Authentication and pass the API key as the password. The username can be any value (for example mail2many or api) — the only important part is that the API key is used as the password:

curl -X GET "https://YOUR_SERVER-api.mail2many.de/api/v1/" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

The Basic Auth header must be sent with every request.

Test authentication​

To test whether your API key works, call the /whoami endpoint. If you receive a response with information about your account, everything is working:

curl -X GET "https://YOUR_SERVER-api.mail2many.de/api/v1/whoami" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Brute-force protection​

For security reasons, repeated failed authentication attempts result in temporary delays:

  • After 5 attempts: 30 seconds lock + 3 additional attempts
  • After 8 attempts: 60 seconds lock + 1 additional attempt
  • After 9 attempts: 120 seconds lock + 1 additional attempt
  • After 10 attempts: 5 minutes lock + 1 additional attempt
  • After 11 attempts: 10 minutes lock + 1 additional attempt
  • From 12 attempts onward: lock duration increases by 5 minutes per failed attempt

All failed attempts are counted only within a 60-minute window. After 60 minutes without additional failures, the counter is reset.

Avoid repeated failed attempts to prevent longer lock periods.