{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"55703b6b-e8ef-c8d5-1cad-a41c1b076d53","name":"Newsletter2Go API","description":"Welcome and thanks for using Newsletter2Go.\n\nThese API docs can be easily made interactive by clicking the `Run in Postman` button on the top right of this site.\n\nIf you don't have an account yet, visit [https://ui.newsletter2go.com/register](https://ui.newsletter2go.com/register) to create a new account.\n\nOnce you have an account, log in and grab your API credentials from [https://ui.newsletter2go.com/api-client](https://ui.newsletter2go.com/api-client).\n\n_Legal Notice:_  \nThis documentation is provided as is by  \nSendinblue GmbH, Köpenicker Str. 126, 10179 Berlin, Germany  \nFull imprint and contact options can be found [here](https://www.newsletter2go.com/imprint)\n\n# Getting Started\n\n1. Download the free [Postman app](https://www.getpostman.com/apps).\n2. Click the `Run in Postman` button on the top right of this site.\n3. Make sure to select the `Newsletter2Go API` environment on the top right in Postman.\n4. Add your [user credentials](https://ui.newsletter2go.com/api-client) to the environment variables\n5. Run the first `Authentication` request. (Your `access token` will be automatically stored within the environment variables)\n6. Make any other subsequent call that you like.\n7. Improve and extend the Postman collection and share your results by creating a pull request in our [Postman collection repository](https://github.com/newsletter2go/api-docs).\n8. You can also watch this [crash course video](https://www.youtube.com/watch?v=Z3n3djbTfSg) on how to get started with our API using Postman.\n    \n\n# Additional Information\n\nFor 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](https://ui.newsletter2go.com). Most likely you will find it there.\n\nIf you found a bug or would like to improve our Postman collection, please create a pull request in our [Github repository](https://github.com/newsletter2go/api-docs).\n\nLast but not least, you can always check our [help docs](https://help.newsletter2go.com) or contact our \\[technical support team\\]([https://mailto:support@newsletter2go.com?subject=Newsletter2Go](https://mailto:support@newsletter2go.com?subject=Newsletter2Go) API documentation).\n\n# JSON First\n\nOur 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.  \nEven though we expect you to send `JSON` payloads, please make sure to use `Content-Type: application/json` in your header when making calls.\n\n# RESTful Principles\n\nOur API follows a very RESTful approach.  \nMost importantly, we support the four standard request methods for `CRUD` operations:\n\n| Method | Description |\n| --- | --- |\n| `POST` | Create a new record |\n| `GET` | Retrieve / read records without changing anything |\n| `PATCH` | Update an existing record |\n| `DELETE` | Delete one or more records |\n\n# HTTP Status Codes\n\nWe follow the most common HTTP status codes when outputting the API response:\n\n## Successful Requests `2xx`\n\n| Response Code | Description |\n| --- | --- |\n| `200` | `OK` Successful request |\n| `201` | `Created` New resource has been created |\n\n## Client Errors `4xx`\n\n| Response Code | Description |\n| --- | --- |\n| `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. |\n| `401` | `Unauthorized` Invalid access_token. Check if the access_token has expired or is incorrect. |\n| `403` | `Forbidden` Access to this resource is denied for this user |\n| `404` | `Not Found` Resource / endpoint is not available |\n\n## Server Error `5xx`\n\nIf you receive a HTTP status code that starts with 5 there's something wrong on our side. Sorry :)  \nPlease contact \\[our support\\]([https://mailto:support@newsletter2go.com?subject=Newsletter2Go](https://mailto:support@newsletter2go.com?subject=Newsletter2Go) API documentation) and we'll try to fix it asap.\n\n# Response Format\n\n``` json\n{\n   \"info\":{\n      \"count\":1\n   },\n   \"value\":[\n      {\n         \"{{key}}\":\"{{value}}\"\n      },\n      ...\n   ]\n}\n\n ```\n\nThe API always returns a `JSON` object with the properties `info` and `value`:\n\n| Property | Description |\n| --- | --- |\n| `info` | Contains the number of results `count` and additional information depending on the resource |\n| `value` | Contains an array of result objects that each can have different keys and values depending on the resource |\n\n# Common `GET` Parameters\n\nThe following parameters are all optional and can be used in every call in order to filter or limit the result sets.\n\n| Parameter | Description |\n| --- | --- |\n| `_filter` | A [complex filter](#filter-language) for filtering the result set based on [FIQL](https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00) |\n| `_limit` | The maximum number of records returned |\n| `_offset` | Pagination for the result set |\n| `_expand` | Submit true to get all default fields for the resource |\n| `_fields` | A comma-separated list of case-sensitive field names to get the values of these fields in the response |\n\n_Example:_\n\n```\nhttps://api.newsletter2go.com/lists/{{list_id}}/recipients?_expand=false&_fields=email,first_name,last_name&_filter=email=LIKE=\"%yahoo%\"&_limit=10&_offset=0\n\n ```\n\n# Filter Language\n\nThe filter language for filtering results is based on [FIQL](https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00).\n\nComparison values have to be \"enquoted\", e.g., \\`first_name==\"Max\"\\`.  \nOtherwise they will be interpreted as attributes themselves, e.g. \\`first_name==last_name\\`\n\nThe following operators are supported:\n\n| Operator | Description | Example |\n| --- | --- | --- |\n| `==` | equals | `age==\"27\"` |\n| `=ne=` | does not equal | `gender=ne=\"m\"` |\n| `=gt=` | greater than | `last_name=gt=\"g\"` |\n| `=ge=` | greater than or equal to | `rating=ge=\"2\"` |\n| `=lt=` | less than | `statistic_mails_clicked=lt=\"5\"` |\n| `=le=` | less than or equal to | `DATE_FORMAT(created_at,\"Y-m-d\")=le=\"2017-09-06\"` |\n| `=like=` | like - use `%` as wildcard | `email=like=\"%yahoo.com\"` |\n| `=nlike=` | not like - use `%` as wildcard | `phone=nlike=\"\"` |\n| `=contains=` | _array_ contains _an element_ | `group_ids=contains=\"rarr38sz\"` |\n| `=ncontains=` | _array_ does not contain _an element_ | `group_ids=ncontains=\"rarr38sz\"` |\n| `=in=` | _an element_ is in _an array_ | `\"rarr38sz\"=in=group_ids` |\n| `=nin=` | _an element_ is not in _an array_ | `\"rarr38sz\"=nin=group_ids` |\n| `;` | logical \"and\" - connect multiple filters | `birthday=ge=\"1979-12-31\";gender==\"f\"` |\n| `,` | logical \"or\" - connect multiple filters | `(group_ids=contains=\"rarr38sz\",group_ids=CONTAINS=\"5cj9y8ub\")` |\n\nMake sure to `urlencode` the `_filter` parameter values when making a request.\n\n_Example:_\n\n```\nhttps://api.newsletter2go.com/lists/{{list_id}}/recipients?_filter=email=LIKE=\"%yahoo%\"\n\n ```\n\n# Transactional Mailings\n\nA 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.  \nSome examples of transactional mailings are:\n\n- order confirmations\n- password change requests\n- registration emails\n- shipping confirmation\n    \n\nOne, if not _the most important_ purpose, of using the Newsletter2Go API is to send transactional emails.  \nOver 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.\n\nIt 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**\n\n#### Step 1\n\nCreate a transactional mailing (we recommend using our UI for that) but [you can also use the API](#a8f42b89-ab89-4ebe-8e5c-8dfe2307341a)\n\n#### Step 2\n\nMake sure the mailing is active (`state==\"active\"`) and copy the `newsletter_id` from the URL. [You can retrieve these values with this endpoint.](#75083638-39a1-4cdf-a307-4e7708e8da76)\n\n#### Step 3\n\nSend the mailing [to a contact in your list or any email address that you pass in the payload of the request](#d39fb18d-bf1f-4255-be78-36f327023b0a)\n\nFirst, you will have to create a new mailing. We recommend that you create that mailing through our [UI](https://ui.newsletter2go.com) 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).\n\nLet 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.\n\nOf 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.\n\nNo 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.\n\nBy 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.\n\nAfter creating a mailing, you will have access to its `ID`. Use that `ID` to actually send the email in the next step.\n\nWhen 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`.\n\nIf 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.\n\nYou 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.  \nThis 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).\n\n# Trying It Out (Postman + Open Source Wrappers)\n\nWe 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.  \nPostman will allow you to execute calls immediately or generate code in every major programming language.\n\nNewsletter2Go also offers some open source wrappers [that can be downloaded here](https://www.newsletter2go.com/features/api-example-implementations/)\n\n# API Reference","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"5017539","team":125350,"collectionId":"55703b6b-e8ef-c8d5-1cad-a41c1b076d53","publishedId":"RWTg1N6k","public":true,"publicUrl":"https://docs.newsletter2go.com","privateUrl":"https://go.postman.co/documentation/5017539-55703b6b-e8ef-c8d5-1cad-a41c1b076d53","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00BAFF"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2022-01-12T14:19:32.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Newsletter2Go API","id":"7e14d3f7-4e1a-4892-9b71-0e94611061a9","owner":"5017539","values":[{"key":"username","value":"{{user_name}}","enabled":true},{"key":"password","value":"{{password}}","enabled":true},{"key":"auth_key","value":"{{auth_key}}","enabled":true},{"key":"refresh_token","value":"{{refresh_token}}","enabled":true},{"key":"access_token","value":"{{access_token}}","enabled":true},{"key":"auth_key_base64","value":"{{auth_key_base64}}","enabled":true},{"key":"auth_key_part_username","value":"{{auth_key_part_username}}","enabled":true},{"key":"auth_key_part_password","value":"{{auth_key_part_password}}","enabled":true},{"key":"list_id","value":"{{list_id}}","enabled":true},{"key":"attribute_id","value":"{{attribute_id}}","enabled":true},{"key":"attribute_name","value":"{{attribute_name}}","enabled":true},{"key":"company_id","value":"{{company_id}}","enabled":true},{"key":"user_id","value":"{{user_id}}","enabled":true},{"key":"recipient_id","value":"{{recipient_id}}","enabled":true},{"key":"group_id","value":"{{group_id}}","enabled":true},{"key":"file_id","value":"{{file_id}}","enabled":true},{"key":"import_id","value":"{{import_id}}","enabled":true},{"key":"newsletter_id","value":"{{newsletter_id}}","enabled":true},{"key":"form_id","value":"{{form_id}}","enabled":true},{"key":"token","value":"[object Object]","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/2487bcbfa98a7d392591b28fd4958615b7b8bf7219193da795e5e472c11b0644","favicon":"https://newsletter2go.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Newsletter2Go API","value":"5017539-7e14d3f7-4e1a-4892-9b71-0e94611061a9"}],"canonicalUrl":"https://docs.newsletter2go.com/view/metadata/RWTg1N6k"}