Skip to main content
API docs by Redocly

mail2many API 1.0 (1.0.0)

Download OpenAPI specification:Download

The mail2many API is a REST API that enables external applications to integrate seamlessly with mail2many. With this API, developers can create, read, update, and delete subscribers and subscriber groups, send newsletters, and retrieve statistics.

API Documentation

If you want to get started with the mail2many API, you should first understand the basic structure of mail2many and its key terms. The API Documentation will guide you through these fundamentals.

API Usage

The API Usage section provides additional details on how to work with the mail2many API.

Languages

Currently the endpoint documentation is only available in english but the Documentation is avaiable in german and english. You can switch the language in the top right

Contact

If you need further assistance, feel free to contact us. You can find the contact form in the footer.

Authentication

Routes for authentication.

Get the account of the api key.

Every api key is assigned to an account. This endpoint returns the account.

Authorizations:
BasicAuth
query Parameters
include
string
Example: include=channels, languages

What relations should be included. Available relations: channels, languages

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Article

Articles are content blocks of newsletters.

Create an new article

Creates an new article and returns it. The placeholders of the article should be filled.

Authorizations:
BasicAuth
Request Body schema: application/json
required

Article object that should be created.

languageIso
string = 5 characters

The language of the article

name
string [ 2 .. 191 ] characters

The internal name of the article

templateId
integer

The template of the article.

canEdit
boolean
Default: true

If the article can be edited.

availableFrom
string or null
Default: null

From which date the article is available in UTC.

availableUntil
string or null
Default: null

Until which date the article is available in UTC.

object

Responses

Request samples

Content type
application/json
{
  • "languageIso": "de",
  • "name": "MacBook Pro 2019",
  • "templateId": 1,
  • "canEdit": true,
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "placeholders": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "name": "MacBook Pro 2019",
  • "templateId": 1,
  • "canEdit": true,
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59"
}

Update an article

Updates an article and returns it. The placeholders of the article can be updated.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the article

Request Body schema: application/json
required

Article object that should be updated.

name
string [ 2 .. 191 ] characters

The internal name of the article

availableFrom
string or null
Default: null

From which date the article is available in UTC.

availableUntil
string or null
Default: null

Until which date the article is available in UTC.

object

Responses

Request samples

Content type
application/json
{
  • "name": "MacBook Pro 2019",
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "placeholders": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "name": "MacBook Pro 2019",
  • "templateId": 1,
  • "canEdit": true,
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59"
}

Channel

Channels are different output channels for the mailings / subscribers.

Get all channels

Returns the available channels of the account. Returns all and not a pagination.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "isDefault": true,
  • "type": 1,
  • "translations": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

CustomerField

Customer fields are specific fields created for a customer.

Get all customer fields

Returns all existing customer fields. If you want to include the defaults, you have to set the include parameter.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: defaults.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "fieldType": 1,
  • "type": 1,
  • "isAvailableForImport": true,
  • "isAvailableForExport": true,
  • "isEditable": true,
  • "inputId": 1,
  • "translations": {
    },
  • "value": "Nepal",
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Sets defaults for a customer field

Sets the default value for a customer field and returns it. Only defaults for account fields can be set. Other types will be skipped. If the account uses multiple languages, the default value can be set for every language. If the default for a language is missing, the global value is used.

Keep in mind that this endpoint returns the customer field. If you want to return the defaults as well, you have to set the include parameter.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the customer field

query Parameters
include
string

Which relations should be included. Available: defaults.

Request Body schema: application/json
required

The defaults which should be set.

value
string

Value for the customer field.

translations
object

Translations for the value of the customer field.

Responses

Request samples

Content type
application/json
{
  • "value": "Müller GmbH",
  • "translations": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "fieldType": 1,
  • "type": 1,
  • "isAvailableForImport": true,
  • "isAvailableForExport": true,
  • "isEditable": true,
  • "inputId": 1,
  • "translations": {
    },
  • "value": "Nepal",
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Sets defaults for multiple customer fields

Sets the default values for multiple customer fields and returns it. Only defaults for account fields can be set. Other types will be skipped. If the account uses multiple languages, the default value can be set for every language. If the default for a language is missing, the global value is used.

Keep in mind that this endpoint returns the customer fields. If you want to return the defaults as well, you have to set the include parameter.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: defaults.

Request Body schema: application/json
required

The defaults which should be set.

Array of objects
Array
id
required
integer

The id of the field: 1=string, 2=integer, 3=date, 4=boolean, 5=string list

value
required
string

Value for the customer field.

translations
object

Translations for the value of the customer field.

Responses

Request samples

Content type
application/json
{
  • "defaults": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "fieldType": 1,
  • "type": 1,
  • "isAvailableForImport": true,
  • "isAvailableForExport": true,
  • "isEditable": true,
  • "inputId": 1,
  • "translations": {
    },
  • "value": "Nepal",
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Mailing

Mailings exists of one or many newsletters.

Get all mailings

Returns all mailings. Newsletters can be included with the paramater ?include=newsletters. You can search and filter the mailings with query parameters.

Authorizations:
BasicAuth
query Parameters
include
string
Example: include=newsletters

What relations should be included. Available relations: newsletters

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Get sent mailings

Returns all sent mailings. Newsletters can be included with the paramater ?include=newsletters.

Authorizations:
BasicAuth
query Parameters
include
string
Example: include=newsletters

What relations should be included. Available relations: newsletters

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Get created trigger mailing

Returns the data of a existing trigger mailing.

The fields isScheduled, isRunning and transferedAt tells the current state of the transmission.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the trigger mailing

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Create a new trigger mailing

Creates a new trigger mailing with the given trigger type and returns it. The next step is to add receivers.

Authorizations:
BasicAuth
Request Body schema: application/json
required

Mailing object that should be created.

triggerTypeId
integer

The id of the trigger type to send.

languageIso
string = 5 characters

The language of the mailing

senderName
string or null [ 2 .. 191 ] characters

The sender name of the mailing

name
string [ 2 .. 191 ] characters

The internal name of the mailing

subject
string

The subject for all newsletters of the mailing.

foreignId
integer

The id of a third-party system. Will be returned in the tracking.

Responses

Request samples

Content type
application/json
{
  • "triggerTypeId": 1,
  • "languageIso": "de",
  • "senderName": "Atrivio",
  • "name": "MacBook Pro 2022",
  • "subject": "Special offer",
  • "foreignId": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Add receivers to created trigger mailing

Adds multiple receivers to the created trigger mailing. 100 can be added with a single request. If all are added the trigger mailing can be scheduled.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the trigger mailing

Request Body schema: application/json
required

Receivers array that should be added.

Array of objects
Array
email
required
string [ 1 .. 155 ] characters

The email of the subscriber.

firstname
string or null [ 1 .. 191 ] characters

The firstname of the subscriber.

lastname
string or null [ 1 .. 191 ] characters

The lastname of the subscriber.

subject
string

The unique subject for the subscriber.

placeholders
object

The placeholders for the receiver. They are defined for every triggerType.

Responses

Request samples

Content type
application/json
{
  • "receivers": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "added": [
    ],
  • "countAdded": 100,
  • "notAdded": [
    ],
  • "countNotAdded": 100
}

Schedule created trigger mailing

Schedules a existing trigger mailing after all receivers were added. It can either be scheduled for now or for a date in the future.

After scheduling mail2many will take care of the transmission. The status can be retrieved with the read route and the statistic can be read with the tracking route.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the trigger mailing

Request Body schema: application/json
required

Date when the trigger mailing should be send.

sendNow
boolean

If the mailing should be send immediately.

sendAt
string

The date and time the mailing should be send as UTC time.

Responses

Request samples

Content type
application/json
{
  • "sendNow": true,
  • "sendAt": "2020-07-23 08:00"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Abort created trigger mailing

Aborts the transmission of the given trigger mailing. If no mails where sent out yet the mailing will be set back to draft. If mails were already sent the mailing will be set to sent.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the trigger mailing

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "languageIso": "de",
  • "mailingTemplateId": 1,
  • "oldVersionFrom": null,
  • "name": "MacBook Pro 2022",
  • "senderName": "Atrivio",
  • "customerFields": {
    },
  • "availableFrom": "2019-08-28 08:00:00",
  • "availableUntil": "2019-09-03 23:59:59",
  • "activeSince": null,
  • "inactiveSince": null,
  • "subscriberChannelId": 1,
  • "isScheduled": false,
  • "isRunning": false,
  • "transferedAt": "2019-09-03 23:59:59"
}

Send a single trigger mailing to a single subscriber

Sends a trigger mailing to a single subscriber within one request.

Authorizations:
BasicAuth
Request Body schema: application/json
required

SingleTrigger object that should be sent.

triggerTypeId
integer

The id of the trigger type to send.

languageIso
string

The language of the trigger mailing.

senderName
string or null [ 2 .. 191 ] characters

The sender name of the mailing

object

Responses

Request samples

Content type
application/json
{
  • "triggerTypeId": 1,
  • "languageIso": "de",
  • "senderName": "Atrivio",
  • "receiver": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Send a single trigger mailing to multiple subscribers

Sends a trigger mailing to multiple subscribers within one request. 100 can be send with a single request.

Authorizations:
BasicAuth
Request Body schema: application/json
required

SingleTrigger object that should be sent.

triggerTypeId
integer

The id of the trigger type to send.

languageIso
string

The language of the trigger mailing.

senderName
string or null [ 2 .. 191 ] characters

The sender name of the mailing

subject
string or null

A global subject for all receivers.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "triggerTypeId": 1,
  • "languageIso": "de",
  • "senderName": "Atrivio",
  • "subject": "Happy Birthday",
  • "receivers": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "sent": [
    ],
  • "countSent": 100,
  • "notSent": [
    ],
  • "countNotSent": 100
}

Newsletter

Newsletters are send to subscribers.

Get all newsletter subscribers.

Returns all subscribers from the given newsletter.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the newsletter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

OptInType

OptInTypes are used to select an optin type for a subscriber.

Get all opt-in types

Returns all existing opt-in types which can be used.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "shortcut": "voucher",
  • "translations": {
    }
}

Parameter

Parameters are per subscriber encrypted data in the newsletters.

Get data from parameter p

Returns data related with the given parameter p.

path Parameters
p
required
string

The parameter p of a mail2many request.

Responses

Response samples

Content type
application/json
{
  • "subscriberId": 1,
  • "newsletterId": 4,
  • "accountId": 2
}

Statistic

Statistics are collected for newsletters.

Get newsletter statistics.

Returns the newsletter statistics data.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the newsletter

query Parameters
statistics
required
string
Examples:
  • details=&baseData=&bounces=&devices=&totalOpenings=&totalClicks=&activity=[object Object]&openingHours=&articleClicks=&privacy=&optouts= - All Statistics

List of statistics

Responses

Response samples

Content type
application/json
{
  • "data": [ ]
}

Subscriber

Subscribers are receivers of mailings.

Get all subscribers

Returns all existing subscribers as pagination. The pagination can be found in the meta key.

Authorizations:
BasicAuth
query Parameters
page
integer
Example: page=1

The page to show starting with 1.

limit
integer
Example: limit=10

How many entries should be returned.

include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Create a single subscriber if not already existing

Creates a new subscriber and returns it. The status and statusAddition must be set correctly, check herefore the subscriber schema. If the subscriber is already existing an error will be returned.

A typical use case for this route is a registration form on a website.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscriber object that should be created.

email
required
string [ 1 .. 155 ] characters

The email of the subscriber.

status
integer
Enum: 1 2 3

The status of the subscriber: 1=receive ready, 2=not receive ready, 3=archived.

statusAddition
integer or null
Enum: 1 2 3 4 5 6

An addition to the status. For the status=1(receive ready) the addition should be null. Possible Additions for status=2(not receive ready): 1=Opt-in pending, 2=no Opt-in, 3=transaction. Possible Additions for status=3(archived): 4=unsubscribed, 5=hard bounced, 6=manual.

sendOptIn
boolean

If an opt-in should be send to the subscriber. Will only be send if status=2 and statusAddition=1

optInLanguageIso
string

The language of the opt-in. If not available optInSent=false will be returned.

genderId
integer
Enum: 1 2 3 4

The gender of the subscriber: 1=male, 2=female, 3=non-binary, 4=not specified.

languageIso
string or null

The language of the subscriber as ISO 639-1

countryIso
string or null

The country of the subscriber as ISO 3166-2

reference
string or null

An dynamic reference for the subscriber. Can be used in different ways: Store-Id, Dealer-Id.

title
string or null [ 1 .. 191 ] characters

The academic title of the subscriber.

firstname
string or null [ 1 .. 191 ] characters

The firstname of the subscriber.

lastname
string or null [ 1 .. 191 ] characters

The lastname of the subscriber.

salutationType
integer
Enum: 1 2 3

The salutation type for the automatic greeting: 1=formal, 2=personal, 3=individual

salutation
string or null [ 1 .. 155 ] characters

An individual salutation for the subscriber.

company
string or null [ 1 .. 191 ] characters

The company of the subscriber.

street
string or null [ 1 .. 191 ] characters

The street of the subscriber.

postcode
string or null [ 1 .. 191 ] characters

The postcode of the subscriber.

city
string or null [ 1 .. 191 ] characters

The city of the subscriber.

phoneNumber
string or null [ 1 .. 191 ] characters

The phone number of the subscriber.

birthday
string or null [ 1 .. 191 ] characters

The birthday of the subscriber in Y-m-d.

optInComment
string or null [ 1 .. 191 ] characters

An opt-in comment for the subscriber.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned.

subscriberGroupNames
Array of strings

The subscriber groups which should be assigned (case sensitive!). If the group with the given name doesn`t exists, it will be created.

customerFields
Array of strings

The customer fields of the subscriber. The ids of the customer fields must be known.

Responses

Request samples

Content type
application/json
{
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "sendOptIn": true,
  • "optInLanguageIso": "de",
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "subscriberGroupIds": [
    ],
  • "subscriberGroupNames": [
    ],
  • "customerFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Delete or archive multiple subscribers via ids or emails

Deletes the subscribers with the given ids or email addresses. Only subscribers who never received a newsletter are deleted. The others will be set to archived.

Authorizations:
BasicAuth
Request Body schema: application/json
required

An array with subscribers which should be deleted. Either ids or emails can be passed.

subscriberIds
Array of integers or null

The subscribers ids which should be deleted.

subscriberEmails
Array of strings or null

The subscribers emails which should deleted.

Responses

Request samples

Content type
application/json
{
  • "subscriberIds": [
    ],
  • "subscriberEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "deletedSubscriberIds": [
    ],
  • "archivedSubscriberIds": [
    ],
  • "deletedSubscriberEmails": [
    ],
  • "archivedSubscriberEmails": [
    ]
}

Get a single subscriber via id, email or uuid

Returns the subscriber with the given id, email or uuid.

Authorizations:
BasicAuth
path Parameters
id
required
string

Id, email or uuid of the subscriber

query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Update a single subscriber via id or email

Updates the subscriber with the given id or email. Only fields which should be updated should be passed. The status and statusAddition must be set correctly, check herefore the subscriber schema. If the subscriber is not existing an error will be returned.

Authorizations:
BasicAuth
path Parameters
id
required
string

Id or email of the subscriber

query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscriber object that should be created.

status
integer
Enum: 1 2 3

The status of the subscriber: 1=receive ready, 2=not receive ready, 3=archived.

statusAddition
integer or null
Enum: 1 2 3 4 5 6

An addition to the status. For the status=1(receive ready) the addition should be null. Possible Additions for status=2(not receive ready): 1=Opt-in pending, 2=no Opt-in, 3=transaction. Possible Additions for status=3(archived): 4=unsubscribed, 5=hard bounced, 6=manual.

genderId
integer
Enum: 1 2 3 4

The gender of the subscriber: 1=male, 2=female, 3=non-binary, 4=not specified.

languageIso
string or null

The language of the subscriber as ISO 639-1

countryIso
string or null

The country of the subscriber as ISO 3166-2

reference
string or null

An dynamic reference for the subscriber. Can be used in different ways: Store-Id, Dealer-Id.

title
string or null [ 1 .. 191 ] characters

The academic title of the subscriber.

firstname
string or null [ 1 .. 191 ] characters

The firstname of the subscriber.

lastname
string or null [ 1 .. 191 ] characters

The lastname of the subscriber.

salutationType
integer
Enum: 1 2 3

The salutation type for the automatic greeting: 1=formal, 2=personal, 3=individual

salutation
string or null [ 1 .. 155 ] characters

An individual salutation for the subscriber.

company
string or null [ 1 .. 191 ] characters

The company of the subscriber.

street
string or null [ 1 .. 191 ] characters

The street of the subscriber.

postcode
string or null [ 1 .. 191 ] characters

The postcode of the subscriber.

city
string or null [ 1 .. 191 ] characters

The city of the subscriber.

phoneNumber
string or null [ 1 .. 191 ] characters

The phone number of the subscriber.

birthday
string or null [ 1 .. 191 ] characters

The birthday of the subscriber in Y-m-d.

detachSubscriberGroups
boolean

If the existing subscriber groups should be detached and only the new ones assigned.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned.

customerFields
Array of strings

The customer fields of the subscriber. The ids of the customer fields must be known.

Responses

Request samples

Content type
application/json
{
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "detachSubscriberGroups": false,
  • "subscriberGroupIds": [
    ],
  • "customerFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Delete or archive a single subscriber via id or email

Deletes the subscriber with the given id or email. He is only deleted when he never received a newsletter. Otherwise he will be set to archived.

Authorizations:
BasicAuth
path Parameters
id
required
string

Id or email of the subscriber

Responses

Response samples

Content type
application/json
{
  • "message": "Resource successfully deleted."
}

Get a single subscriber via parameter p

Returns the subscriber related with the given parameter p.

Authorizations:
BasicAuth
path Parameters
p
required
string

The parameter p of a mail2many request.

query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Registers a single subscriber

Registers the given subscriber in the account. If the subscriber is not existing, he will be created and an opt-in will be send. If he is existing, he will be updated and an opt-in will send, when he is not already receive-ready.

A typical use case for this route is a registration form on a website. You can allways call this route and mail2many takes care of the necessary steps.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscriber that should be registered.

email
required
string [ 1 .. 155 ] characters

The email of the subscriber.

optInLanguageIso
string

The language of the opt-in. If not available optInSent=false will be returned.

genderId
integer
Enum: 1 2 3 4

The gender of the subscriber: 1=male, 2=female, 3=non-binary, 4=not specified.

languageIso
string or null

The language of the subscriber as ISO 639-1

countryIso
string or null

The country of the subscriber as ISO 3166-2

reference
string or null

An dynamic reference for the subscriber. Can be used in different ways: Store-Id, Dealer-Id.

title
string or null [ 1 .. 191 ] characters

The academic title of the subscriber.

firstname
string or null [ 1 .. 191 ] characters

The firstname of the subscriber.

lastname
string or null [ 1 .. 191 ] characters

The lastname of the subscriber.

salutationType
integer
Enum: 1 2 3

The salutation type for the automatic greeting: 1=formal, 2=personal, 3=individual

salutation
string or null [ 1 .. 155 ] characters

An individual salutation for the subscriber.

company
string or null [ 1 .. 191 ] characters

The company of the subscriber.

street
string or null [ 1 .. 191 ] characters

The street of the subscriber.

postcode
string or null [ 1 .. 191 ] characters

The postcode of the subscriber.

city
string or null [ 1 .. 191 ] characters

The city of the subscriber.

phoneNumber
string or null [ 1 .. 191 ] characters

The phone number of the subscriber.

birthday
string or null [ 1 .. 191 ] characters

The birthday of the subscriber in Y-m-d.

detachSubscriberGroups
boolean

If the existing subscriber groups should be detached and only the new ones assigned.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned.

subscriberGroupNames
Array of strings

The subscriber groups which should be assigned (case sensitive!). If the group with the given name doesn`t exists, it will be created.

customerFields
Array of strings

The customer fields of the subscriber. The ids of the customer fields must be known.

forceOptIn
boolean

If an opt-in should be forced for existing subscribers.

Responses

Request samples

Content type
application/json
{
  • "email": "mail@example.com",
  • "optInLanguageIso": "de",
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "detachSubscriberGroups": false,
  • "subscriberGroupIds": [
    ],
  • "subscriberGroupNames": [
    ],
  • "customerFields": {
    },
  • "forceOptIn": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "email": "mail@example.com",
  • "status": 2,
  • "statusAddition": 1,
  • "genderId": 4,
  • "languageIso": "de",
  • "countryIso": "de",
  • "reference": "123456",
  • "title": "Dr.",
  • "firstname": "Florian",
  • "lastname": "Reichart",
  • "salutationType": 1,
  • "salutation": "Hi Florian",
  • "company": "Atrivio",
  • "street": "Albert-Einstein-Str. 6",
  • "postcode": "87437",
  • "city": "Kempten",
  • "phoneNumber": "+49 831 512999-0",
  • "birthday": "1970-01-01",
  • "optInComment": "Opt-in was given",
  • "optInSent": true,
  • "customerFields": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Updates multiple subscriber via id or email

Updates the given subscribers via id or email. He should pass either id or email for every subscriber. The id will be checked first. Only fields which should be updated should be passed. The status and statusAddition must be set correctly, check herefore the subscriber schema. If the subscriber is not existing he will be ignored.

If all subscribers should be added to the same subscriber groups the subscriberGroupIds should be passed at the first level and removed from the subscribers array for performance increase.

The rights of the api key will be checked here. If the key has not the right to set unsubscribed subscribers to receive-ready, the old status will be kept.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscribers that should be updated.

Array of objects

The subscribers which should updated.

detachSubscriberGroups
boolean

If the existing subscriber groups should be detached and only the new ones assigned.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned to every subscriber. Should be used when every subscriber must be added in the same group.

Responses

Request samples

Content type
application/json
{
  • "subscribers": [
    ],
  • "detachSubscriberGroups": false,
  • "subscriberGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": [
    ],
  • "invalid": [
    ],
  • "failed": [
    ]
}

Create multiple subscribers if not already existing

Creates the given subscribers if not existing. The status and statusAddition must be set correctly, check herefore the subscriber schema. If the subscriber is already existing he will be ignored.

If all subscribers should be added to the same subscriber groups the subscriberGroupIds should be passed at the first level and removed from the subscribers array for performance increase.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscribers that should be created.

Array of objects

The subscribers which should created.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned to every subscriber. Should be used when every subscriber must be added in the same group.

Responses

Request samples

Content type
application/json
{
  • "subscribers": [
    ],
  • "subscriberGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "created": [
    ],
  • "invalid": [
    ],
  • "failed": [
    ]
}

Returns the optOuts of subscribers in a period

Returns the optOuts of the subscribers. An period should be send in the search field.

Authorizations:
BasicAuth
query Parameters
search
string
Example: search=[object Object]&search=[object Object]

The search to apply.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "action": "optOut",
  • "email": "florian.reichart@atrivio.de",
  • "newsletterId": 1,
  • "timestamp": "2019-09-30 06:00:00",
  • "ip": "127.0.0.1"
}

Update existing subscribers via id or email or create new subscribers if not existing

Send an array of subscribers to mail2many. Existing subscribers will be updated and new subscribers created. The status and statusAddition must be set correctly, check herefore the subscriber schema.

If all subscribers should be added to the same subscriber groups the subscriberGroupIds should be passed at the first level and removed from the subscribers array for performance increase.

A typical use case for this route is a data synchronization between a third-party-system and mail2many.

The rights of the api key will be checked here. If the key has not the right to set unsubscribed subscribers to receive-ready, the old status will be kept.

Authorizations:
BasicAuth
query Parameters
include
string

Which relations should be included. Available: subscriberGroups, newsletters, channels.

Request Body schema: application/json
required

Subscribers that should be created or updated.

Array of objects

The subscribers which should be created or updated.

detachSubscriberGroups
boolean

If the existing subscriber groups should be detached and only the new ones assigned.

subscriberGroupIds
Array of integers

The subscriber groups which should be assigned.

Responses

Request samples

Content type
application/json
{
  • "subscribers": [
    ],
  • "detachSubscriberGroups": false,
  • "subscriberGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "created": [
    ],
  • "updated": [
    ],
  • "invalid": [
    ],
  • "failed": [
    ]
}

Archive one or multiple subscribers via id or email

Archives the given subscribers in the given channels. If no channel ids are given, the subscribers will be archived in all assigned channels.

It is possible to archive subscribers by their ids or by their emails. If both ids and emails are given, both will be used to archive the subscribers. You should select one of the two options.

Authorizations:
BasicAuth
Request Body schema: application/json
required

Subscribers that should be archived.

subscriberIds
Array of integers

The subscriber ids which should be archived.

subscriberEmails
Array of integers

The subscriber emails which should be archived.

channelIds
Array of integers

The channel ids which should be archived.

Responses

Request samples

Content type
application/json
{
  • "subscriberIds": [
    ],
  • "subscriberEmails": [
    ],
  • "channelIds": [
    ]
}

Response samples

Content type
application/json
{
  • "totalCount": 2,
  • "processedCount": 2
}

SubscriberGroup

SubscriberGroups are used to group subscriber.

Get all subscriber groups

Returns all existing subscriber groups.

Authorizations:
BasicAuth
query Parameters
returnAll
boolean
Example: returnAll=false

If all groups should be returned. By default entries are returned paginated.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Contest 2019",
  • "type": 3,
  • "subscriberCount": 1,
  • "receiveReadyCount": 1,
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "pluginId": 1,
  • "isCalculating": false,
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Create a new subscriber group

Creates a new subscriber group and returns it. Subscribers can be added to the group by id or email. If the subscriberGroup with the given name is already existing an error will be returned.

Authorizations:
BasicAuth
Request Body schema: application/json
required

SubscriberGroup object that should be created. The name field is required, the other fields are optional.

name
string [ 1 .. 155 ] characters

The unique name of the group

type
integer

The type of the group: 1 = static, 2 = dynamic, 3 = external

subscriberIds
Array of integers or null

The subscribers which should be added to the group by id.

subscriberEmails
Array of strings or null

The subscribers which should be added to the group by email.

canEdit
boolean

If the group can be edited from the user

canDelete
boolean

If the group can be deleted from the user

canAssign
boolean

If the user can assign subscribers to the group

isCalculating
boolean

If the subscribers are currently calculating

Responses

Request samples

Content type
application/json
{
  • "name": "Contest 2019",
  • "type": 3,
  • "subscriberIds": [
    ],
  • "subscriberEmails": [
    ],
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "isCalculating": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Contest 2019",
  • "type": 3,
  • "subscriberCount": 1,
  • "receiveReadyCount": 1,
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "pluginId": 1,
  • "isCalculating": false,
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Get a existing group

Returns the subscriber group with the given id.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the group

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Contest 2019",
  • "type": 3,
  • "subscriberCount": 1,
  • "receiveReadyCount": 1,
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "pluginId": 1,
  • "isCalculating": false,
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Update an existing subscriber group

Updates an existing subscriberGroup and returns it. Subscribers can be added to the group by id or email. If the subscriberGroup with the given name is already existing an error will be returned.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the group

Request Body schema: application/json
required

SubscriberGroup object that should be updated. All fields are optional.

name
string or null [ 1 .. 155 ] characters

The unique name of the group

subscriberIds
Array of integers or null

The subscribers which should be added to the group by id.

subscriberEmails
Array of strings or null

The subscribers which should be added to the group by email.

detach
boolean

If the given subscribers should be detached from the group instead of attached.

sync
boolean

All subscribers will be detached from the given group and only the given subscribers get attached.

canEdit
boolean

If the group can be edited from the user

canDelete
boolean

If the group can be deleted from the user

canAssign
boolean

If the user can assign subscribers to the group

isCalculating
boolean

If the subscribers are currently calculating

Responses

Request samples

Content type
application/json
{
  • "name": "Contest 2019",
  • "subscriberIds": [
    ],
  • "subscriberEmails": [
    ],
  • "detach": false,
  • "sync": true,
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "isCalculating": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Contest 2019",
  • "type": 3,
  • "subscriberCount": 1,
  • "receiveReadyCount": 1,
  • "canEdit": true,
  • "canDelete": true,
  • "canAssign": true,
  • "pluginId": 1,
  • "isCalculating": false,
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}

Delete a existing subscriber group

Deletes the subscriber group with the given id.

Authorizations:
BasicAuth
path Parameters
id
required
integer

Id of the group

Responses

Response samples

Content type
application/json
{
  • "message": "Resource successfully deleted."
}

Tracking

Trackings are user actions like opening, click, unsubscribe.

Get all trackings

Returns the trackings data of all mailings. The trackings can be filtered and sorted. Check the developers guide to see how this works.

Authorizations:
BasicAuth
query Parameters
page
integer
Example: page=1

The page to show starting with 1.

limit
integer
Example: limit=10

How many entries should be returned.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "type": "click",
  • "isFirst": true,
  • "subscriberId": 1,
  • "subscriberEmail": "mail@example.com",
  • "mailingId": 1,
  • "foreignId": 1,
  • "newsletterId": 1,
  • "articleId": 1,
  • "areaId": 1,
  • "placeholderId": 1,
  • "timestamp": "2019-09-03 23:59:59",
  • "target": "https://www.atrivio.de",
  • "userAgent": "Chrome",
  • "platform": "OS X",
  • "deviceType": 1
}

TriggerType

Trigger types are different types of external triggers like birthay, forgot password.

Get all trigger types

Returns the available trigger types of the account and if a mailing for the type is existing and activated. Returns all and not a pagination.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "shortcut": "birthday",
  • "usages": {
    },
  • "translations": {
    },
  • "createdAt": "2019-09-27 10:51:00",
  • "updatedAt": "2019-09-27 10:52:00"
}