Newsletter2Go API

Welcome and thanks for using Newsletter2Go.

These API docs can be easily made interactive by clicking the Run in Postman button on the top right.

If you don't have an account yet, visit https://ui.newsletter2go.com/register to create a new account.

Once you have an account, log in and grab your API credentials from https://ui.newsletter2go.com/api-client.

Getting Started

  1. Download the free Postman app or the Chrome browser extension
  2. Click the Run in Postman button on the top right
  3. Make sure to select the Newsletter2Go API environment on the top right
  4. Add your user credentials to the environment variables
  5. Run the first Authentication request. (Your access token will be automatically stored within the environment variables)
  6. Make any other subsequent call that you like
  7. Improve and extend the Postman collection and share your results by creating a pull request in our Postman collection repository

Additional Information

For simplicity’s sake, we have only documented the most important API calls on this page. If you cannot find a call that you need or expect to be there, make sure to monitor the network tab when navigating our user interface. Most likely you will find it there.

If you found a bug or would like to improve our Postman collection, please create a pull request in our Github repository.

Last but not least, you can always check our help docs or contact our technical support team.

JSON First

Our REST API exchanges data in the JSON data format. Every parameter / payload you pass (with very few exceptions, e.g., when you upload files) should therefore be formatted in JSON and our API will always return results in JSON as well.
Even though we expect you to send JSON payloads, please make sure to use Content-Type: application/json in your header when making calls.

RESTful Principles

Our API follows a very RESTful approach. Most importantly, we support the four standard request methods for CRUD operations:

Method Description
POST Create a new record
GET Retrieve / read records without changing anything
PATCH Update an existing record
DELETE Delete one or more records

HTTP Status Codes

We follow the most common HTTP status codes when outputting the API response:

Successful Requests 2xx

Response Code Description
200 OK Successful request
201 Created New resource has been created

Client Errors 4xx

Response Code Description
400 Bad Request Inspect the body for detailed information about what went wrong. The most common error is "code":1062, which means that a unique constraint was hit. For example, if the name of the group is already in use.
401 Unauthorized Invalid access_token. Check if the access_token has expired or is incorrect.
403 Forbidden Access to this resource is denied for this user
404 Not Found Resource / endpoint is not available

Server Error 5xx

If you receive a HTTP status code that starts with 5 there's something wrong on our side. Sorry :)
Please contact our support and we'll try to fix it asap.

Response Format

{
   "info":{
      "count":1
   },
   "value":[
      {
         "{{key}}":"{{value}}"
      },
      ...
   ]
}

The API always returns a JSON object with the properties info and value:

Property Description
info Contains the number of results count and additional information depending on the resource
value Contains an array of result objects that each can have different keys and values depending on the resource

Common GET Parameters

The following parameters are all optional and can be used in every call in order to filter or limit the result sets.

Parameter Description
_filter A complex filter for filtering the result set based on FIQL
_limit The maximum number of records returned
_offset Pagination for the result set
_expand Submit true to get all default fields for the resource
_fields A comma-separated list of case-sensitive field names to get the values of these fields in the response

Example:

https://api.newsletter2go.com/lists/{{list_id}}/recipients?_expand=false&_fields=email,first_name,last_name&_filter=email%3DLIKE%3D%22%25yahoo%25%22&_limit=10&_offset=0

Filter Language

The filter language for filtering results is based on FIQL.

Comparison values have to be "enquoted", e.g., `first_name=="Max"`. Otherwise they will be interpreted as attributes themselves, e.g. `first_name==last_name`

The following operators are supported:

Operator Description Example
== equals age=="27"
=ne= does not equal gender=ne="m"
=gt= greater than last_name=gt="g"
=ge= greater than or equal to rating=ge="2"
=lt= less than statistic_mails_clicked=lt="5"
=le= less than or equal to DATE_FORMAT(created_at,"Y-m-d")=le="2017-09-06"
=like= like - use % as wildcard email=like=%yahoo.com
=nlike= not like - use % as wildcard phone=nlike=""
=contains= array contains an element group_ids=contains="rarr38sz"
=ncontains= array does not contain an element group_ids=ncontains="rarr38sz"
=in= an element is in an array "rarr38sz"=in=group_ids
=nin= an element is not in an array "rarr38sz"=nin=group_ids
; logical "and" - connect multiple filters birthday=ge="1979-12-31";gender=="f"
, logical "or" - connect multiple filters (group_ids=contains="rarr38sz",group_ids=CONTAINS="5cj9y8ub")
Make sure to urlencode the _filter parameter values when making a request.

Example:

https://api.newsletter2go.com/lists/{{list_id}}/recipients?_filter=email%3DLIKE%3D%22%25yahoo%25%22

Transactional Mailings

One, if not the most important purpose, of using the Newsletter2Go API is to send transactional emails.
Over the last couple of years we have optimized this process in order to offer this very powerful feature to single developers as well as professional teams.

It is very important to understand the following concept in order for you to take full advantage of our personalization features and our detailed reports when sending transactional emails. So please read carefully

Step 1

Create a transactional mailing (we recommend using our UI for that) but you can also use the API

Step 2

Make sure the mailing is active (state=="active") and copy the newsletter_id from the URL

Step 3

Send the mailing to a contact in your list or any email address that you pass in the payload of the request

First, you will have to create a new mailing. We recommend that you create that mailing through our UI in order to take full advantage of our powerful newsletter builder. This way, we will automatically create cross-client optimized and responsive HTML. Yet another advantage lies in the possibility for other users (e.g., the marketing team) to change the layout or the content of the mailing without having to contact the developer (you).

Let the marketing team take care of design and content. All you need is the ID of the transaction mailing. You will never have to change any code.

Of course, it is also possible to create a mailing entirely through the API. When doing so, you can take advantage of our cross-client optimized responsive auto-generated HTML by using our JSON/YAML based Newsletter2Go Markup Language.

No matter how you create the mailing, try to create one reusable template. You can customize individual emails by inserting placeholders for personalized fields such as name, products or other information that will be filled through an API call when sending.

By only creating one template, you can take advantage of our full reporting since all emails will be treated part of a single campaign. When you or a team member changes that template, we will create a new version of the mailing in the background and you will be able to see the difference in performance in the reports. This is particularly useful when you are trying to test and optimize different versions of transactional emails such as a sign-up email.

After creating a mailing, you will have access to its ID. Use that ID to actually send the email in the next step.

When sending an email, you have to pass the newsletter ID and information about the recipient. Either pass the recipient ID or pass all the recipient's data (including the email-address) as JSON.

If you only pass the recipient ID, we will use his or her data from your list to personalize the mailing. If you pass full recipient data as JSON, we will try to merge the data with existing data from your list.

You can also pass additional data such as product data that is not saved in your list. Just make sure that the placeholders in the source of the mailing correspond to the parameters that you are passing. This way you can also create for-loops, which can be useful if you pass different amounts of data for each recipient (e.g., a purchase confirmation where you want to list all the products that were just bought).

Trying It Out (Postman + Open Source Wrappers)

We highly recommend using our Postman collection to develop our API. Just click the Run in Postman button on the top right to get started. Once the collection loads, make sure to fill the environment variables with your credentials.
Postman will allow you to execute calls immediately or generate code in every major programming language.

Newsletter2Go also offers some open source wrappers:
PHP Wrapper

API Reference

PUBLISHER

Newsletter2Go

CATEGORIES

Imports

200+