Skip to main content

API‑Key

The API key is essential for accessing the mail2many API. An API key authenticates your application and grants access to exactly one account.

Create and manage API keys​

An account can have multiple API keys with different permissions. This allows you to use separate keys for different purposes or third-party applications:

Account 1 (Customer A)
│
├─ API key "Website": abc123.1a2b3c4d5e6f...
│  └─ Permissions: Subscribers
│
├─ API-Key "CRM": xyz789.7x8y9z1a2b3c...
│  └─ Permissions: Subscribers
│
└─ API key "Campaign Tool": def567.5d6e7f8a9b0c...
  └─ Permissions: Articles

If you have an admin user in the mail2many account, you can create API keys in the settings area. Otherwise, ask an admin to create an API key for you.

Permissions​

Each API key has a set of permissions that restrict access to the account. These permissions are defined when the key is created and can be changed at any time.

API-Scopes​

API scopes define which resources an API key may access:

  • Articles (articles) Create and update articles.

  • Subscribers (subscribers) Create and update subscribers.

Advanced permissions​

In addition to scopes, API keys can have special permissions:

  • Change "Archived, unsubscribed" to "Ready to receive" Allows reactivating unsubscribed subscribers via the API.

  • Change "Archived, manual" to "Ready to receive" Allows reactivating manually archived subscribers.

  • Change "Archived, spam complaint" to "Ready to receive" Allows reactivating subscribers with spam complaints.

  • Archive "Ready to receive" Allows archiving subscribers who are ready to receive.

  • Allow unknown subscribers for trigger mailings Allows sending to subscribers who do not yet exist in the system.

Default opt-in mailing​

The default opt-in mailing is configured on the API key. This mailing is sent automatically when a new subscriber is created via API with an opt-in requirement.

info

Important: The default opt-in mailing is relevant when new subscribers are added through the API and email confirmation is required (double opt-in).

The opt-in mailing can be selected when creating the API key or adjusted later in settings.

Security​

info

Important: Since the API key grants full access to the account, it must remain secret. Treat it like a password.

  • Transfer the API key only over secure channels (HTTPS).
  • Store it securely and never in source code or public repositories.
  • If you suspect compromise, delete the key immediately and create a new one.
  • Use separate keys for different applications to improve security.

API‑Key Format​

The API key always has a prefix, followed by a dot and the unique key:

{PREFIX}.{UNIQUE_KEY}

Example: abc123.1a2b3c4d5e6f...

The prefix is unique and helps identify the API key.

Authentication​

The API key is sent as the password in the Basic Auth header. The username can be any value (for example, use mail2many or api):

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

The Basic Auth header must be included in every request.

Check account​

If you want to verify which account your API key accesses, use the /whoami endpoint:

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"

This endpoint returns information about the account your API key can access.