Getting started

The mail2many API provides external programs access to mail2many data and functionality. It allows developers to integrate mail2many in their website or own application. The API can be used for a lot of different use cases, from a simple forwarding of the website registrations to complex subscriber sync, everything is possible.

To use the mail2many API, you need access to an mail2many account. Once you have an account and are logged-in, you can create an API key and begin making calls to the API.

REST

The mail2many API generally follows the REST conventions:

• Different resources are available like subscribers or mailings
• HTTP methods are used for actions like GET or POST
• Requests must send data generally in the JSON
• Responses are generally in the JSON

The mail2many API only supports data exchange in the JSON. XML or simple POST parameters are not supported due to the scope and maintainability.

It is advisable to transmit the two headers "Content-Type:application/json" and "Accept:application/json" to ensure best communication.

Endpoint documentation

We are using the OpenAPI Specification to describe our endpoints.

URL

The url of the API is https://{server}-api.mail2many.de/api/v1/ where {server} corresponds to the server of your account. For example if your server is 127 the API endpoints for your accounts are available at https://127-api.mail2many.de/api/v1/

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

The endpoint documentation describes all available endpoinnts annd it also allows testing our enndpoints directly.

You must authenticate requests using your API key. Users can generate and manage multiple API keys within their mail2many account. An API key is always linked to a mail2many account where it was created.

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.

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 contain every available field, plz scheck the Schema if a field can be nullable and is therefore not required.

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.

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
}

Advanced

In this section same advanced topics are presented.

All dates are returned in the format YYYY-MM-DD HH:MM:SS and are UTC (Universal Time Coordinated). You have to tranform 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. All contained filters are linked with AND, the values within a filter are linked with OR.

search=[
    $key: $value
]

search=[
    $key: [
        $firstValue,
        $secondValue
    ]
]

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

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. All contained sortings are executed one after the other.

sorting=[
    {
        $key: $order
    }
]

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

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.

{
    "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.

Variables

In mail2many it is possible to upload your own HTML. In this HTML, so-called variables can be printed. A distinction is made between simple variables and variable areas.

Die Variablen und variablen Bereiche können mit dem Testversand getestet werden. Hierbei werden auch Daten des Empfängers verwendet, sofern der Empfänger im Account vorhanden ist.

The following variables are available.

The simple variables must be inserted with the help of an ID and should have a default value. This value is used if the variable cannot be replaced for the subscriber. A separate default value must be set for each variable.

The variables must be inserted in the following form:

{{V:ID:DEFAULT}}

{{V:4:Germany}}

{{V:2:}}

The other possibility is to work with variable areas. Here you can define whole text areas and each area can contain plain text as well as multiple variables. Each area has to have a unique area number and a fallback. If one of the variables in the area cannot be replaced for the subscriber, the default value is used. This variant is more flexible because you can combine text and multiple variables.

Attention: In this case, you have not to define a default for each variable, which is why the syntax is a little different.

The variable areas must be inserted in the following form. Make sure that keep the area number unique:

[[A:-:AREA-NUMBER:-:TEXT:-:DEFAULT]]

[[A:-:1:-:Hello {{V:1}} {{V:3}}:-:Hello]]

[[A:-:2:-:Greetings to {{V:4}}:-:Many greetings]]

Customer fields

In mail2many it is possible to define individual fields for every customer. These fields can be created by us as a customer request. Every field gets an unique id and has a field and data type.

There are two different field types: Subscriber and Account. While the subscriber fields can be set for ever single subscriber, the account field can only be set once in an account. Examples for a customer field could be their favourite country or if they are VIP subscriber. An account field could for example be the company name.

These are the two available field types:

• subscriber
• account

Additionally every field has one of the following data types:

• string
• integer
• date
• boolean

The subscriber fields can be saved in every subscriber request within the key customerFields. You must use their correct id and pass the correct data types. In this example we have these 4 fields:

• Favourite country (string)
• Number of booked trips (integer)
• Last trip (date)
• VIP subscriber (boolean)

The request could look the the following:

{
    "email": "florian.reichart@atrivio.de",
    "customerFields": {
        "1": "Nepal",
        "2": 2,
        "3": "2018-06-01",
        "4": true
    }
}

The accounts fields must be saved directly in the account. There is a special route for saving the default value, check the customer field section. This could look like the following:

{
  "value": "My Company name"
}

The customer fields can be used in the same way variables can. The only different is that C must be used instead of V.

Please check the following examples:

{{C:1:Europe}}

The customer fields can also be used in the variable areas and be combined with variables.

[[A:-:1:-:Hello {{V:1}} {{C:3}}:-:Hello]]

Own pages

In mail2many it is possible to store own pages for opt-in confirmations and unsubscriptions for an account. The aim is for a subscriber to be able to confirm and unsubscribe in a familiar environment.

With a own confirmation page you can present your subscribers a familiar environment after he confirmed the opt-in. The confirmation itself still takes place in mail2many, the unsubscribe page only functions as a target page. This way the register and confirmation pages can be on the same website.

Prepare page

First, the confirmation page must be implemented. The confirmation page must be a publicly accessible HTML page to which mail2many can redirect when an opt-in is confirmed. The page itself can be implemented with an accompanying programming language.

The page should be on the same domain as the sender address. If you send your newsletter with newsletter@atrivio.de, for example, the confirmation page should be on the domain atrivio.de.

When someone wants to confirm the opt-in, mail2many forwards to the external page and passes one parameters in the url:

The unsubscribe page must evaluate the valid parameter. If it has the value "true" as a string, then the confirmation has been done and a confirmation page should be displayed.

If this is not the case and the value is "false" as string, then the subscriber was too late and the opt-in was no longer valid. In this case, the subscriber should be informed that the confirmation could not be done and he has to subscribe again.

The entire process could look like this:

• The subscriber registers on your website.
• mail2many sends him a opt-in mailing with a validity of 7 days
• The subscriber confirms the opt-in within the 7 days by clicking the button in the mail
• mail2many confirms the subscriber and redirects him to your page with valid=true
• You show the subscriber a cofirmation page

If the subscriber would confirm after 7 days, mail2many would not confirm him and redirect him to your page with valid=false.

A simple PHP code could look like this:

• newsletter-confirmation-example.txt

Store page url

The second and last step is to set up the confirmation page in the respective account. This can be done very easily in the "Settings" area. The link to your page for can be stored there under "Opt-In and Opt-Out".

Two different pages

If you want to create a page for successful registrations and a separate page for expired registrations, this is also possible. You can store two pages under "Opt-In and Opt-Out".

With a own unsubscribe page you can present your subscribers a familiar environment to unsubscribe. The unsubscription itself still takes place in mail2many, the unsubscribe page only functions as an intermediate page and forwards the subscriber to mail2many. This way the unsubscription can be on the same website as the registration.

Attention

If the unsubscribe page is not available or not working correctly, the subscribers cannot unsubscribe from your account. Make sure the connection is setup correctly.

Prepare page

First, the unsubscribe page must be implemented. The unsubscribe page must be a publicly accessible HTML page to which mail2many can redirect when an unsubscription occurs. The page itself can be implemented with an accompanying programming language.

The page should be on the same domain as the sender address. If you send your newsletter with newsletter@atrivio.de, for example, the unsubscribe page should be on the domain atrivio.de.

When somebody wants to unsubscribe, mail2many forwards to the external page and passes three parameters in the url:

The unsubscribe page must first evaluate the unsubscribed parameter. If it has the value "true" as a string, then the unsubscription has already been done and a confirmation page should be displayed.

If this is not the case and the value is "false" as string, then the subscriber wants to unsubscribe. In this case, a page where he can confirm the unsubscription should be displayed. If the subscriber confirms, for example, with a button, he must be forwarded back to the mail2many. The mail2many parameter p and the parameter force=true must be transferred to tell mail2many to unsubscribe him now. Then mail2many will unsubscribe him and him redirect back.

The entire process could look like this:

• The subscriber clicks the unsubscribe link in the newsletter
• mail2many redirects him to the your unsubscribe page and appends the parameters
• The subscriber is shown a page to confirm due to unsubscribed=false
• The subscriber clicks a "Confirm" button
• The subscriber is redirected back to mail2many with the parameter p and force=true and unsubscribed there
• mail2many redirects the subscriber again back to the unsubscribe page and appends parameters to it
• Recipient is shown the confirmation of unsubscription due to unsubscribed=true

A simple PHP code could look like this:

• newsletter-unsubscribe-example.txt
• newsletter-unsubscribe-erfolgreich-sucessful.txt

Store page url

The second and last step is to set up the unsubscribe page in the respective account. This can be done very easily in the "Settings" area. The link to your page for can be stored there under "Opt-In and Opt-Out".