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 of this site.

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.

Legal Notice:
This documentation is provided as is by
Sendinblue GmbH, Köpenicker Str. 126, 10179 Berlin, Germany
Full imprint and contact options can be found here

Getting Started

• Download the free Postman app.
• Click the Run in Postman button on the top right of this site.
• Make sure to select the Newsletter2Go API environment on the top right in Postman.
• Add your user credentials to the environment variables
• Run the first Authentication request. (Your access token will be automatically stored within the environment variables)
• Make any other subsequent call that you like.
• Improve and extend the Postman collection and share your results by creating a pull request in our Postman collection repository.
• You can also watch this crash course video on how to get started with our API using Postman.

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](https://mailto:support@newsletter2go.com?subject=Newsletter2Go API documentation).

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:

HTTP Status Codes

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

Successful Requests 2xx

Client Errors 4xx

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](https://mailto:support@newsletter2go.com?subject=Newsletter2Go API documentation) 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:

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.

Example:

https://api.newsletter2go.com/lists/{{list_id}}/recipients?_expand=false&_fields=email,first_name,last_name&_filter=email=LIKE="%yahoo%"&_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:

Make sure to urlencode the _filter parameter values when making a request.

Example:

https://api.newsletter2go.com/lists/{{list_id}}/recipients?_filter=email=LIKE="%yahoo%"

Transactional Mailings

A transactional mailing is a type of mailing that is highly customized, sent to a single individual at a custom time mostly through the system and triggered by an API call.
Some examples of transactional mailings are:

• order confirmations
• password change requests
• registration emails
• shipping confirmation

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. You can retrieve these values with this endpoint.

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 that can be downloaded here

API Reference