Introduction

The mail2many API provides you access to mail2many data and functionality. It allows you to integrate mail2many in your website or own application. The API can be used for a lot of different scenarios, from a simple forwarding registrations from the website to complex subscriber syncs or sending out trigger mailings, a lot is possible.

To get started you should use the /whoami endpoint. If you get a response with your account information, everything is working.

REST

The mail2many API generally follows the REST conventions:

• Different resources are available at different endpoints like subscribers, subscribeGroups or mailings
• HTTP methods are used to interact with the resources like GET, POST, PUT or DELETE
• Requests must send data generally in the JSON
• Responses are generally in the JSON

The mail2many API only supports data exchange in the JSON format. XML or other formats are not supported.

You should always send the headers "Content-Type:application/json" and "Accept:application/json" to ensure that the data is correctly interpreted. Otherwise the API will return not what you expect.

Endpoint documentation

We are using the OpenAPI Specification to describe our endpoints.

The url of the API is https://127-api.mail2many.de/api/v1/.

The automatic generated endpoint documentation is available at https://127-api.mail2many.de/api/v1/documentation.

The endpoint documentation describes all available endpoints and it also allows testing our endpoints directly. You can also see the schemas of the resources and the request and response examples.

You must authenticate requests using an API key. Users can generate and manage multiple API keys in their mail2many account. An API key is always linked to a single mail2many account and can have different permissions.

The key grant access to an mail2many account and should therefore be treated as passwords. External applications should always store the keys in a theft-proof manner and ensure that they are not visible anywhere. Handle them like passwords.

To make an request use the HTTP basic authentication and send the API key as password. The API lets you use any string as the username. Use the API key as password.

As already mentioned the data is exchanged usually in JSON.

Request

The request body must be send as JSON. Every endpoint requires different data, which data can be found in the endpoint documentation. Please note that the example requests always contain every available field. Plase check the Schema if a field can be nullable and is therefore not required. Send only the the fields you need.

An example body could like the following:

{
    "email": "florian.reichart@atrivio.de",
    "lastname": "Reichart",
    "firstname": "Florian",
    "genderId": 1,
    "sendOptIn": true
}

Response

The response has an http status code and the body is usually send as JSON. Which data the endpoints are returning is described in the endpoint documentation.

Normally the response contains more fields than the request as mail2many returns all fields of the resource and meta information like the id or the creation date.

An example respose could like the following:

Status: 200
{
    "id": 1,
    "email": "florian.reichart@atrivio.de",
    "status": 2,
    "statusAddition": 1,
    "genderId": 1,
    "languageIso": "de",
    "firstname": "Florian",
    "lastname": "Reichart",
    "company": null,
    "street": null,
    "postcode": null,
    "city": null,
    "phoneNumber": null,
    "birthday": null,
    "optInComment": null,
    "optInSent": true,
    "createdAt": "2021-01-22 10:28:00",
    "updatedAt": null
}

All dates are returned in the format YYYY-MM-DD HH:MM:SS and are in UTC (Universal Time Coordinated). You have to transform it into your desired timezone.

2021-01-22 10:28:00

The mail2many API allows you to filter the results for certain endpoints. This can be done with the help of the search parameter. This parameter must always be a JSON and passed to the url. All contained filters are linked with AND, the values within a filter are linked with OR.

?search=[{"languageIso":"de"}]

search=[
    {
        "$key": "$value"
    }
]

search=[
    {
        "languageIso":"de"
    }
]

search=[{"languageIso":"de"}]

search=[
    {
        "$key":[
            $firstValue,
            $secondValue
        ]
    }
]

search=[
    {
        "genderId":[
            1,
            2
        ]
    }
]

search=[{"genderId":[1,2]}]

search=[
    {
        "$key":
            {
                "condition":"$condition",
                "value":"$value"
            }
    }
]

search=[
    {
        "email":
            {
                "condition":"like",
                "value":"%atrivio.de%"
            }
    }
]

search=[{"email":{"condition":"like","value":"%atrivio.de%"}}]

The following conditions are available:

The mail2many API allows you to sort the results for certain endpoints. This can be done with the help of the sorting parameter. This parameter must always be a JSON in the url. All contained sortings are executed one after the other.

?sorting=[{"createdAt":"desc"}]

sorting=[
    {
        "$key": "$order"
    }
]

sorting=[
    {
        "createdAt":"desc"
    }
]

sorting=[{"createdAt":"desc"}]

sorting=[
    {
        "$key1": "$order1"
    },
    {
        "$key2": "$order2"
    }
]

sorting=[
    {
        "createdAt":"desc"
    },
    {
        "email":"asc"
    }
]


sorting=[{"createdAt":"desc"},{"email":"asc"}]

The following conditions are available:

Some endpoints use pagination. This can be recognised if a meta.pagination field is present in the response. By default 10 entries are delivered. This can be overwritten by passing the parameter limit. With the help of the parameter page, it can be determined which page is to be delivered. How many pages are available in total can be checked in meta.pagination.

?limit=20&page=1

{
    "meta": {
        "pagination": {
            "total": 40,
            "count": 20,
            "perPage": 20,
            "currentPage": 1,
            "totalPages": 2,
            "links": {
                "next": ""
            }
        }
    }
}

In the event of an error, the mail2many API returns a meaningful error message. In addition to a readable error message, an error code is also always delivered. A http status code for the request is delivered as well.

The following errors exist in general. For individual errors check the endpoint documentation.

Invalid data

If invalid data is transferred, an error message in the following format will be returned. The field errors contains all fields which werer invalid and the reason why they are invalid.

If the data is invalid, the whole request is rejected and the status code is 422. You have to correct the data and try again.

{
    "status": "error",
    "code": 1002,
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email must be a valid email address."
        ],
        "firstname": [
            "The firstname must be a string."
        ]
    },
    "statusCode": 422
}

Resource already existing

If an entry is already existing the error message looks like the following.

{
    "status": "error",
    "code": 1024,
    "message": "The resource is already existing.",
    "errors": [],
    "statusCode": 409
}

When using our API, keep in mind that sometimes errors or exceptions can occur. To ensure that your integration works reliably, you should always catch API errors and exceptions.

If an endpoint returns an error, you should log the call in as much detail as possible. Ideally, you should save the transmitted data and the received data including the header information. This way, you can later understand what happened and, if necessary, make the request again.

Please note that mail2many sometimes has to work with large amounts of data. In this case, requests may take longer. Set your timeout accordingly.

For loading data it is better to work with a sensible pagination. For creating or updating data it can be useful to not to transfer too much data at once. For example, if you want to synchronise subscribers, do not send 10,000 recipients in one request, but make 10 requests with 1000 recipients each.

Also check how often you need to make certain requests. Sometimes hourly requests are necessary, other times one request per day would be enough. With this you can help mail2many to be less busy.