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>"
Pagination
The following parameters can be applied to list requests:
Parameter | Description |
---|---|
page | Defines the page number |
take | Limits the number of results (At most 100 entries will be returned if no limit is defined) |
EXAMPLE:
GET /<resource>/?page=2&take=20
The following parameters are used for this request:
- Show results starting from the 21 entry (page=2)
- Show 20 entries (take=20)
Subscribers
see all operations for subscribers.List subscribers
/subscribers
Filter Parameters
Name | Required | Type | Description |
---|---|---|---|
optional | string | Search a subscriber by email |
EXAMPLE:
curl -H "Authorization: Bearer <token>" https://www.netmailer.ch/<client>/api/subscribers
Result Format
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
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
}
Result Format
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
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
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
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
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
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
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
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
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
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
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"
}
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
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
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