Skip to main content

Getting Started

To get started with the mail2many API, use the /whoami endpoint. If you receive a response with information about your account, everything is working correctly:

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"

Request lifecycle​

How an API request flows from authentication to response:

1. Authentication
   │ Authorization: Basic bWFpbDJtYW55OllPVVJfQVBJX0tFWQ==
   │
2. Send request
   │ POST /subscribers
   │ Body: {"email": "...", "firstname": "..."}
   │
3. Server processing
   │ ├─ Verify authentication
   │ ├─ Rate limit check (600/min, 10 concurrent)
   │ ├─ Request validation
   │ └─ Data processing
   │
4. Response
   └─ 201 Created + Subscriber object (JSON)

REST API fundamentals​

The mail2many API is resource-oriented and follows REST principles:

  • Resources are available through different endpoints, e.g. channels, subscribers, subscriberGroups, or mailings
  • HTTP methods (GET, POST, PUT, DELETE) are used to interact with resources
  • Requests and responses use the JSON format
  • The API supports only JSON — XML or other formats are not supported

Request and response headers​

Set the following headers in your requests:

Content-Type: application/json
Accept: application/json

This ensures the API can correctly interpret your data.

Technical limits​

Consider API limits early in your integration:

  • 600 requests per minute per API key
  • maximum of 10 concurrent requests per API key

For details and headers, see Rate Limiting.

OpenAPI documentation​

Available endpoints are documented using the OpenAPI Specification. You can find the Endpoint Documentation.