Getting started

The Netmailer API is a REST interface. The API supports the following HTTP verbs:

Verb Description
GET requests a resource from the server.
POST creates a new resource.
PUT edits an existing resource.
DELETE deletes a resource.

HTTP-Codes

Actions and errors yield different HTTP response codes. Please have a look at the expected response codes in the following list.

Code Description
200 Request OK
201 New resource created
400 The request parameters are invalid
401 The bearer token or the provided api key is invalid
403 You do not possess the required rights to access this resource.
404 The resource could not be found / is unknown.
500 An unexpected condition was encountered

HTTP-Headers

You must provide the following headers in each request:

Header Valid values Description
Accept application/json You can only use the format application/json for the moment only JSON format is supported.
Authorization Bearer %token% Token configured in your account, you must provide the authorization header with the encrypted token using base64 encoding for secure transmission.

Security

Every request must contain the "Authorization: Bearer <token>", the token is used to authenticate the user in the API and to be able to consume the resources

You must be a verified user to make API requests. You can authorize against the API with an API token.

The Netmailer API uses "Authorization: Bearer <token>" for authorizing requests. If you don't have a token. Please contact us

The token is configurable in your NetMailer account under Settings > Web service UUID. This UUID needs to be base64 encoded and this encoded string should be sent as the token. Remember to always connect using https or your token could be exposed.

EXAMPLE:

                curl -H "Authorization: Bearer <token>" <resource_url>

Errors

When the Authorization is not valid in any way the API will respond with a HTTP Status Code 401 and a "WWW-Authenticate" header

In the header you will be able to see the specific error of the authorization

HEADER EXAMPLE:

                WWW-Authenticate: Bearer realm="<error_message>"

Subscribers

see all operations for subscribers.

List subscribers

/subscribers

Filter Parameters

Name Required Type Description
email optional string Search a subscriber by email

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscribers

Result Format

Success Failure 

Status: 200 OK
[
    {
        "id": 1,
        "salutation": "Mr.",
        "languageCode": "de",
        "company": "Paweco",
        "title": "Chief Technology Officer",
        "firstName": "Dino",
        "lastName": "Butcher",
        "gender": "m",
        "address": "123 Some Street",
        "zipCode": "1234",
        "city": "Some City",
        "countryId": 10,
        "phone": "+1234543453",
        "fax": "+3242232342",
        "email":"some@email.com",
        "active": true,
        "birthdate": "2017-12-31",
        "freeText1": "Some text",
        "freeText2": "",
        "freeText3": "",
        "created": "2015-11-24T23:23:31",
        "timestamp": "2015-11-24T23:23:31",
        "deactivationDate": "2015-11-24T23:23:31",
        "hardbouncedDate": "2015-11-24T23:23:31"
    },{
        "id": 2,
        "salutation": "Mr.",
        "languageCode": "de",
        "company": "Paweco",
        "title": "Chief Operating Officer",
        "firstName": "Patrick",
        "lastName": "Trussel",
        "gender": "m",
        "address": "123 Some Street",
        "zipCode": "1234",
        "city": "Some City",
        "countryId": 10,
        "phone": "+1234543453",
        "fax": "+3242232342",
        "email":"some@email.com",
        "active": true,
        "birthdate": "2017-12-31",
        "freeText1": "Some text",
        "freeText2": "",
        "freeText3": "",
        "created": "2015-11-24T23:23:31",
        "timestamp": "2015-11-24T23:23:31",
        "deactivationDate": "2015-11-24T23:23:31",
        "hardbouncedDate": "2015-11-24T23:23:31"
    }
]
Status: 404 NOT FOUND
{
    "error" : "no subscribers"
}

Show subscriber

/subscribers/1

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscribers/1

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "gender": "m",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "active": true,
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "created": "2015-11-24T23:23:31",
    "timestamp": "2015-11-24T23:23:31",
    "deactivationDate": "2015-11-24T23:23:31",
    "hardbouncedDate": "2015-11-24T23:23:31"
}
Status: 404 NOT FOUND
{
    "error" : "subscriber not found"
}

Create subscriber

/subscribers

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X POST https://www.netmailer.ch/<client>/api/subscribers

BODY:

{
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "subscriber_group_ids": [ 1, 2, 3, 4 ],
    "db_Optin": true
}

Double optin

Result Format

Success Failure 

Status: 201 CREATED
{
    "id": 1,
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "gender": "m",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "active": true,
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "created": "2015-11-24T23:23:31",
    "timestamp": "2015-11-24T23:23:31",
    "deactivationDate": "2015-11-24T23:23:31",
    "hardbouncedDate": "2015-11-24T23:23:31"
}
Status: 400 BAD REQUEST
{
    "error" : "bad request"
}

Update subscriber

/subscribers/1

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X PUT https://www.netmailer.ch/<client>/api/subscribers/1

BODY:

{
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "active": true,
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "subscriber_group_ids": [ 1, 2, 3, 4 ]
}

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "gender": "m",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "active": true,
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "created": "2015-11-24T23:23:31",
    "timestamp": "2015-11-24T23:23:31",
    "deactivationDate": "2015-11-24T23:23:31",
    "hardbouncedDate": "2015-11-24T23:23:31"
}
Status: 400 BAD REQUEST
{
    "error" : "bad request"
}

Delete subscriber

/subscribers/1

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X DELETE https://www.netmailer.ch/<client>/api/subscribers/1

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "salutation": "Mr.",
    "languageCode": "de",
    "company": "Paweco",
    "title": "Chief Technology Officer",
    "firstName": "Dino",
    "lastName": "Butcher",
    "gender": "m",
    "address": "123 Some Street",
    "zipCode": "1234",
    "city": "Some City",
    "countryId": 10,
    "phone": "+1234543453",
    "fax": "+3242232342",
    "email":"some@email.com",
    "active": false,
    "birthdate": "2017-12-31",
    "freeText1": "Some text",
    "freeText2": "",
    "freeText3": "",
    "created": "2015-11-24T23:23:31",
    "timestamp": "2015-11-24T23:23:31",
    "deactivationDate": "2015-11-24T23:23:31",
    "hardbouncedDate": "2015-11-24T23:23:31"
}
Status: 400 BAD REQUEST
{
    "error" : "bad request"
}

Subscriber Groups

see all operations for subscriber groups.

List subscriber groups

/subscriber-groups

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscriber-groups

Result Format

Success Failure 

Status: 200 OK
[
    {
        "id": 1,
        "name": "Sample Subscriber Group",
        "languageCode": "de",
        "description": "Some description text",
        "welcomeNewsletterId": 1,
        "public": true
    },
    {
        "id": 2,
        "name": "Sample Subscriber Group",
        "languageCode": "de",
        "description": "Some description text",
        "welcomeNewsletterId": 1,
        "public": true
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no subscriber groups" 
}

Show subscriber group

/subscriber-groups/:id

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscriber-groups/1

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": true
}
Status: 404 NOT FOUND
{ 
    "error" : "subscriber group not found" 
}

Create subscriber group

/subscriber-groups

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X POST https://www.netmailer.ch/<client>/api/subscriber-groups

BODY:

{
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": true
}

Result Format

Success Failure 

Status: 201 CREATED
{
    "id": 1,
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": true
}
Status: 400 BAD REQUEST
{ 
    "error" : "bad request" 
}

Update subscriber group

/subscriber-groups/:id

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X PUT https://www.netmailer.ch/<client>/api/subscriber-groups/1

BODY:

{
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": false
}

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": false
}
Status: 400 BAD REQUEST
{ 
    "error" : "bad request" 
}

Delete subscriber group

/subscriber-groups/:id

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X DELETE https://www.netmailer.ch/<client>/api/subscriber-groups/1

Result Format

Success Failure 

Status: 200 OK
{
    "id": 1,
    "name": "Sample Subscriber Group",
    "languageCode": "de",
    "description": "Some description text",
    "welcomeNewsletterId": 1,
    "public": false
}
Status: 400 BAD REQUEST
{ 
    "error" : "bad request" 
}

List subscriber group subscribers

/subscriber-groups/:id-subscriber-group/subscribers

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscriber-groups/1/subscribers

Result Format

Success Failure 

Status: 200 OK
[
    {
        "id": 1,
        "salutation": "Mr.",
        "languageCode": "de",
        "company": "Paweco",
        "title": "Chief Technology Officer",
        "firstName": "Dino",
        "lastName": "Butcher",
        "gender": "m",
        "address": "123 Some Street",
        "zipCode": "1234",
        "city": "Some City",
        "countryId": 10,
        "phone": "+1234543453",
        "fax": "+3242232342",
        "email":"some@email.com",
        "active": true,
        "birthdate": "2017-12-31",
        "freeText1": "Some text",
        "freeText2": "",
        "freeText3": "",
        "created": "2015-11-24T23:23:31",
        "timestamp": "2015-11-24T23:23:31" 
    },{
        "id": 2,
        "salutation": "Mr.",
        "languageCode": "de",
        "company": "Paweco",
        "title": "Chief Operating Officer",
        "firstName": "Patrick",
        "lastName": "Trussel",
        "gender": "m",
        "address": "123 Some Street",
        "zipCode": "1234",
        "city": "Some City",
        "countryId": 10,
        "phone": "+1234543453",
        "fax": "+3242232342",
        "email":"some@email.com",
        "active": true,
        "birthdate": "2017-12-31",
        "freeText1": "Some text",
        "freeText2": "",
        "freeText3": "",
        "created": "2015-11-24T23:23:31",
        "timestamp": "2015-11-24T23:23:31" 
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no subscribers in subscriber group" 
}

List subscribers groups by id

subscriber-groups/subscriber/:id

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscriber-groups/subscriber/1

Result Format

Success Failure 

Status: 200 OK
[
    {
    "id":34,
    "idSubscriberGroup":23,
    "idSubscriber":1
    },{
    "id":35,
    "idSubscriberGroup":24,
    "idSubscriber":1
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no subscribers in subscriber group" 
}

Add subscriber to subscriber group

/subscriber-groups/:id-subscriber-group/subscribers

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X POST https://www.netmailer.ch/<client>/api/subscriber-groups/1/subscribers

BODY:

The content of the data structure sent to our servers can be the "id" or the "email" of the subscriber. Either one would work in order to retrieve the resource and add it to a subscriber group.

{
    "id": 234234,
    "email":"some@email.com"
}

Result Format

Success Failure 

Status: 201 CREATED
Status: 400 BAD REQUEST
{ 
    "error" : "bad request" 
}

Remove subscriber from subscriber group

/subscriber-groups/:id-subscriber-group/subscribers

EXAMPLE:

                curl -H "Authorization: Bearer <token>" -X DELETE https://www.netmailer.ch/<client>/api/subscriber-groups/1/subscribers

BODY:

The content of the data structure sent to our servers can be the "id" or the "email" of the subscriber. Either one would work in order to retrieve the resource and add it to a subscriber group.

{
    "id": 234234,
    "email":"some@email.com"
}

Result Format

Success Failure 

Status: 200 OK
Status: 400 BAD REQUEST
{ 
    "error" : "bad request" 
}

Newsletters

see all operations for newsletters.

List newsletters

/newsletters/:language-code/?type=<type>

Filter Parameters

Name Required Type Description
draft optional string Possible values: "false" or "true" (default "true")
type optional string Possible values: "welcome" (default: "normal")

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/newsletters/en/?draft=false

Result Format

Success Failure 

Status: 200 OK
[
    {
        "id": 1,
	"code": "4C6884CA-155D-CE52-23474A9480FB1B03",
	"title": "First Newsletter",
	"intDescription": "Some internal description",
	"previewText": "Some preview text",
	"sendDate": "2019-01-18 18:50:21.0",
	"senderAddress": "PAWECO GmbH ‹newsletter@paweco.ch›",		
        "languageCode": "de",
        "type": "normal",
	"countEmailsSent": "1234",
	"countOpened": "456",
	"countOpenedUnique": "321",
	"countClicks": "123"
    },
    {
        "id": 2,
	"code": "4C6884CA-155D-CE52-23474A9480FB1B04",
        "title": "Second Newsletter",
	"intDescription": "Some internal description",
	"previewText": "Some preview text",
	"sendDate": "2019-01-19 19:50:21.0",
	"senderAddress": "PAWECO GmbH ‹newsletter@paweco.ch›",		
    	"languageCode": "de",
    	"type": "normal",
	"countEmailsSent": "1234",
	"countOpened": "456",
	"countOpenedUnique": "321",
	"countClicks": "123"
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no newsletters" 
}

Salutations

see all operations for salutations.

List salutations

/salutations/?languageCode=<language-code>

Filter Parameters

Name Required Type Description
languageCode required string Possible values: "en","fr","de","it"

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/salutations/?languageCode=en

Result Format

Success Failure 

Status: 200 OK
[
    {
        "id": 1,
        "label": "Mr.",
        "gender": "m",
        "languageCode": "en"
    },
    {
        "id": 2,
        "label": "Mrs.",
        "gender": "f",
        "languageCode": "en"
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no salutations" 
}

Languages

see all operations for languages.

List languages

/languages/:language-code

EXAMPLE:

                curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/languages/en

Result Format

Success Failure 

Status: 200 OK
[
    {
        "code": "en",
        "name": "English"
    },
    {
        "code": "de",
        "name": "German" 
    }
]
Status: 404 NOT FOUND
{ 
    "error" : "no languages" 
}