Tokens

You need to add a sending domain token to authenticate your API requests. API tokens are generated for sending domains and can have different permissions to limit which areas of your account they may be used to access.

Create a token

Create an API token with this POST request:

POST  https://api.mailersend.com/v1/token

Request Body

{
    "name": "API Token",
    "domain_id": "Domain ID",
    "scopes" : ["email_full", "analytics_read"]
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TokenParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->token->create(
    new TokenParams('token name', 'domainId', TokenParams::ALL_SCOPES)
);

More examplesopen in new window

const MailerSend = require("mailersend");

const mailersend = new MailerSend({
    api_key: "key",
});

mailersend.createToken({
  name: "Token name",
  domain_id: "xxx",
  scopes: [
    "email_full",
    "domains_read",
    "domains_full",
    "activity_read",
    "activity_full",
    "analytics_read",
    "analytics_full",
    "tokens_full",
  ]
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  });

More examplesopen in new window

from mailersend import tokens

api_key = "API key here"

mailer = tokens.NewToken(api_key)

scopes = ["email_full", "analytics_read"]

mailer.create_token("my-token", scopes)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	domainID := "domain-id"
	
	scopes := []string{
		"tokens_full", 
		"email_full",
		"domains_full",
		"activity_full",
		"analytics_full",
		"webhooks_full",
		"templates_full",
	}

	options := &mailersend.CreateTokenOptions{
		Name:     "token name",
		DomainID: domainID,
		Scopes:   scopes,
	}

	newToken, _, err := ms.Token.Create(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
	
	// Make sure you keep your access token secret
	log.Print(newToken.Data.AccessToken)
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.tokens.Token;
import com.mailersend.sdk.tokens.TokenAdd;
import com.mailersend.sdk.tokens.TokenScopes;

public void CreateToken() {
    
    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
        TokenAdd token = ms.tokens().addBuilder()
            .name("Test token")
            .domainId("domain id")
            .addScope(TokenScopes.activityFull)
            .addScope(TokenScopes.analyticsFull)
            .addToken();
        
        System.out.println(token.id);
        System.out.println(token.name);
        System.out.println(token.accessToken);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_tokens = Mailersend::Tokens.new
ms_tokens.create(name: "Very nice token", scopes: %w[ email_full domains_read ], domain_id: "yourdomainid")

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`name`	`string`	yes	Max: `50`
`domain_id`	`string`	yes
`scopes`	`array`	yes

Possible scopes

 [
     "email_full",
     "domains_read",
     "domains_full",
     "activity_read",
     "activity_full",
     "analytics_read",
     "analytics_full",
     "tokens_full",
     "webhooks_full",
     "templates_full",
     "suppressions_read",
     "suppressions_full",
     "sms_full",
     "sms_read",
   ]

Responses

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json

{
  "data": {
    "id": "b74c547a741e199d29c2bb38703fc4642c486841ab568b9fddc83be12329727022f6fb98291efd62",
    "accessToken": "[redacted]",
    "name": "Token",
    "created_at": "2020-06-10 10:10:14"
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Update a token

Update an API token with this PUT request:

PUT https://api.mailersend.com/v1/token/{token_id}/settings

Request Body

{
    "status": "pause"
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TokenParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->token->update('token_id', TokenParams::STATUS_PAUSE); // PAUSE
$mailersend->token->update('token_id', TokenParams::STATUS_UNPAUSE); // UNPAUSE

More examplesopen in new window

const MailerSend = require("mailersend");

const mailersend = new MailerSend({
    api_key: "key",
});

mailersend.updateToken({
  token_id: "xxx",
  status: "pause"
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  });

More examplesopen in new window

from mailersend import tokens

api_key = "API key here"

mailer = tokens.NewToken(api_key)

# pause
mailer.update_token("my-token")

# unpause
mailer.update_token("my-token", pause=False)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	tokenID := "token-id"
	
	updateOptions := &mailersend.UpdateTokenOptions{
		TokenID: tokenID,
		Status:  "pause/unpause",
	}

	_, _, err := ms.Token.Update(ctx, updateOptions)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.tokens.Token;

public void CreateToken() {
    
    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {

        // true to pause it, false to unpause it
        Token token = ms.tokens().updateToken(T"token id", true);
        
        System.out.println(token.name);
        System.out.println(token.status);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
        fail();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_tokens = Mailersend::Tokens.new
ms_tokens.update(token_id: "d2220fx04", status: "paused")

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations	Details
`status`	string	no	`pause`, `unpause`

Responses

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json

{
  "data": {
    "id": "b74c547a741e199d29c2bb38703fc4642c486841ab568b9fddc83be12329727022f6fb98291efd62",
    "name": "Token",
    "status": "pause",
    "created_at": "2020-06-10 10:10:15"
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Delete a token

Delete an API token with this DELETE request:

DELETE  https://api.mailersend.com/v1/token/{token_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`token_id`	string	yes

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TokenParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->token->delete('token_id');

More examplesopen in new window

const MailerSend = require("mailersend");

const mailersend = new MailerSend({
    api_key: "key",
});

mailersend.deleteToken({
  token_id: "xxx"
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  });

More examplesopen in new window

from mailersend import tokens

api_key = "API key here"

mailer = tokens.NewToken(api_key)

mailer.delete_token("token-id")

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	tokenID := "token-id"
	
	_, err := ms.Token.Delete(ctx, tokenID)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.tokens.Token;

public void CreateToken() {
    
    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        MailerSendResponse response = ms.tokens().deleteToken("token to delete");
        
        System.out.println(response.responseStatusCode);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_tokens = Mailersend::Tokens.new
ms_tokens.delete(token_id: "d2220fx04")

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 404 Not Found

# Tokens

# Create a token

# Request Body

# Request parameters

# Possible scopes

# Responses

# Valid

# Error

# Update a token

# Request Body

# Request parameters

# Responses

# Valid

# Error

# Delete a token

# Request parameters

# Responses

# Valid

# Error

Tokens

Create a token

Request Body

Request parameters

Possible scopes

Responses

Valid

Error

Update a token

Request Body

Request parameters

Responses

Valid

Error

Delete a token

Request parameters

Responses

Valid

Error