Authenticating to the API.
The authentication to our API is based on the OAuth 2.0 protocol.
In order to interact with the Newsletter2Go API you need to authenticate and retrieve an access token that will be sent in every request. This is called a bearer token.
We’ll guide you through the steps to obtain the token. You can also follow this video tutorial on how to do it using Postman.
First, you need to have your Newsletter2Go registered username, password and Auth-Key. You can find these credentials in your account API information.
Auth-Key: mc6s4gnaf_D5x71v9Z_g4f1Fq_b421tVHBad_m51FTj:a259g6tz3 username: foo@bar.com password: mypassword123
Copy your Auth-Key and encode it to Base64 format. One way to do this is by using an online encoding tool.
This is an example of how your Auth-Key should look before and after being converted to Base64.
Auth-Key: mc6s4gnaf_D5x71v9Z_g4f1Fq_b421tVHBad_m51FTj:a259g6tz3 Base64: bWM2czRnbmFmX0Q1eDcxdjlaX2c0ZjFGcV9iNDIxdFZIQmFkX201MUZUajphMjU5ZzZ0ejM=
The Base64 is just a more complex representation of the Auth-Key string, which is needed for the authentication protocol to work. In the end, they both represent the same.
Let’s build the authentication POST request.
The request is made of two parts, headers and body.
Headers
For the headers, you have to set two variables, Content-Type and Authorization.
Content-Type defines the kind of data that’ll be exchanged in the request. For the Newsletter2Go API, you should always set this variable to application/json.
Authorization is the variable that will carry the Base64 encoded key. Make sure to use the word Basic before your Base64 encoded key.
For this example, your headers should look like this :
{
"Content-Type": "application/json",
"Authorization":"Basic bWM2czRnbmFmX0Q1eDcxdjlaX2c0ZjFGcV9iNIxdFZIQmFkX201MUZUajphMjU5ZzZ0ejM="
}
Body
For the body, you will need to set three variables: username, password and grant_type.
Your username should be the email address you use to log into your Newsletter2Go account. We recommend creating an API dedicated user with all permissions granted. You can check out this article on how to create multiple users.
Your password is your Newsletter2Go account password.
You should always set the variable grant_type to https://nl2go.com/jwt.
For this example, the body should look like this :
{
"username": "foo@bar.com",
"password": "mypassword123",
"grant_type": "https://nl2go.com/jwt"
}<br>
Execute the POST request. Here is how the HTTP request should look like for this example:
POST /oauth/v2/token HTTP/1.1
Host: api.newsletter2go.com
Content-Type: application/json
Authorization: Basic bWM2czRnbmFmX0Q1eDcxdjlaX2c0ZjFGcV9iNIxdFZIQmFkX201MUZUajphMjU5ZzZ0ejM=
{
"username": "foo@bar.com",
"password": "mypassword123",
"gant_type": "https://nl2go.com/jwt"
}<br>
You’ll get a response from the server.
{
"access_token": "__eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfXy5haWQiOjgzLCJfXy5lbnZpcm9ubWVudCI6InByb2R1Y3Rpb24iLCJfXy5leHBpcmVzQXQiOjE1MzM4MzIxNTEsIl9fLnNjb3BlIjoiIiwiX18uY2lkIjoiMTEzOTFfbUE2VkdQX1F0UF FwU19ac0t4TkVxVF9hUUhzbzNVRnduIiwiX18ucmQxIjo4ODA5MSwiX18ucmQyIjo5OTEzM30.aXsdQt2NwZBlsLz_6EwArMIeG01nBJpGIasBMJnuDCw",
"expires_in": 7200,
"token_type": "bearer",
"scope": null,
"refresh_token": "__eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfXy5haWQiOjgzLCJfXy5lbnZpcm9ubWVudCI6InByb2R1Y3Rpb24iLCJfXy5leHBpcmVzQXQiOjE1MzY0MTY5NTEsIl9fLnNjb3BlIjoiIiwiX18uY2lkIjoiMTEzOTFfbUE2VkdQX1F0UFFwU19ac0t4TkVxVF9hUUhzbzNVRnduIiwiX18ucmQxIjo1OTAyLCJfXy5yZDIiOjM4Mzc1LCJfXy5yZWZyZXNoIjp0cnVlfQ.1YfNt1fY-5Q9u1cZF8BhLetWIireq98spTyAspsDAuA",
"account_id": "awtfn5jn",
"type": "user"
}<br>
The attribute access_token is the bearer token that you should use in the header of all subsequent calls. Always placed after the word Bearer.
{
"Authorization": "Bearer <access_token>"
}
The access_token will expire in 2 hours (7200 seconds). You can get a new access_token by sending the refresh_token to this endpoint.