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://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 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, unsubscriptions and errors for an account. The aim is for a subscriber to be able to confirm, unsubscribe and see errors 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".

With a own error page you can present your subscribers a familiar environment after an error occured.

Prepare page

First, the error page must be implemented. The error page must be a publicly accessible HTML page to which mail2many can redirect when an error 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 error page should be on the domain atrivio.de.

When an error occurs mail2many forwards to the external page and passes the reason in the url:

The error page can evaluate the reason parameter and display a specific error message.

It is of course also possible to display a general error page.

Store page url

The second and last step is to set up the error 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".

Possible error reasons (Exceptions)

Trigger mailings

mail2many allows external systems to send so-called trigger mailings to receivers. They are called trigger mailings because the transmission is triggered external from third-party-system.

The trigger mailings must be created and activated in mail2many, and have a so-called TriggerType. The TriggerType helps to identify the correct mailing. If the mailing changes in mail2many, the API call does not have to be adapted if the TriggerType remains the same. The types can be requested with the endpiont GET /triggerTypes. Please note that the language of the mailing is also important as the trigger mailing can exist in multiple languages.

In addition to the TriggerType the trigger mailings can have placeholders. The placeholders are different for each TriggerType and are defined beforehand. Before you send a trigger mailing you have to know the placeholders. The values for the placeholders then must be transferred per receiver. Since they are transferred per receiver, each receiver can receive a different content.

The are two different types of trigger mailings.

Single triggers mailings are triggered by an external action or event and mail2many send them directly to a single receiver. An good example is the password-reset mail. It can be triggered by a external system when a customer requests a new password. The customer expects to get the password-reset mail instant and only a single customer must be contacted.

The statistics of single trigger mailings are always added up. This means, for example, that you can see the total open rate across all send single trigger mailings.

There are two different endpoints for sending this type of mailings. The first one is the POST /mailings/singleTrigger. This route is suitable to send a single trigger mailing to a single receiver.

The second one is POST /mailings/singleTrigger/batch. As the name suggests this endpoint can be used to send the same single trigger mailing to multiple receivers within one request to mail2many. Up to 100 receivers can be triggered in a single request. This endpoint is intended for triggering several receivers in one request. Nevertheless, the placeholders allow the receivers to receive different content.

In mail2many every mailing has a sender name and subject which is maintained by the editor. But its possible to overwrite the values with the singleTrigger-endpoints. The sender name can be overwritten globally at the top level. The subject can also be overwritten globally. However, it is also possible to transfer a separate subject for each receiver.

The other type are so-called campaigns. These differ a little from the single trigger mailings. With this type, a copy of the trigger mailing must first be created. Then any number of receivers are transmitted for the previously created copy. In the last step, the copied mailing must be scheduled for dispatch.

mail2many then sends the mails to the receivers in the background. You can check the status of the transmission by querying the mailing model with the endpoint GET /mailings/trigger/{id}. The copy makes it possible to record the statistics individually per campaign.

The first endpoint to create the copy is POST /mailings/trigger. Receivers can be transfered with the POST /mailings/trigger/{id}/receivers endpoint. The scheduling must be done with POST /mailings/trigger/{id}/schedule.

The rules for sender name and subject also apply to the campaigns. The stored sender name and subject can be overwritten globally when creating the mailing copy. The subject can optionally be adjusted per receiver if necessary.

Both types use trigger mailings in the background and can be called from external. So how do the two types differ?

The single trigger is particularly suitable if a single or few receivers are to be written to. It is also preferable when sending is to be done directly. It should not be a problem if the statistic is collected across all transmissions.

If you want to write to larger numbers of receivers and evaluate the statistics individually, the campaign trigger is suitable. The dispatch is done in the background and the statistics are created individually for each campaign.

Channels

Mail2many supports the use of channels. Channels can be used if you want to send different types of newsletters in one mail2many account. The channels are then assigned to both the subscribers and the mailings.

Subscribers can subscribe or unsubscribe to individual channels. When creating a mailing you must select the channel of the mailing. Only subscribers who have subscribed to the corresponding channel receive the newsletter.

It is therefore possible to send different newsletters in one mail2many account, which can also have their own layout.

A requirement for using the channels is that the account has booked the Channels module. Afterwards, new channels can be created in the account settings.

To read the channels you can use the GetAllChannels endpoint. This provides you with all channels of an account with ID and the name as used in mail2many.

You will then need this information when dealing with subscribers. Instead of a global status, you have to work with a status per channel.

Get

When reading subscribers, it may be necessary to obtain the information about the channels. In this case, you must send an include parameter in the URL. This could look like this, for example:

?include=channels