MailerSend Developers

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.

List tokens

List API token with this GET request:

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

Request parameters

Query parameterTypeRequiredLimitationsDetails
pageintno
limitintnoMin: 10, Max: 100Default: 25

Request Body

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

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b1aaaaaaaaa",
      "name": "First token",
      "status": "unpause",
      "created_at": "2024-04-12T11:27:53.000000Z",
      "scopes": [
        "email_full"
      ]
    },
    {
      "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b12aaaaaaaaa",
      "name": "Second token",
      "status": "unpause",
      "created_at": "2024-04-17T08:40:13.000000Z",
      "scopes": [
        "domains_read",
        "analytics_full"
      ]
    }
  ]
}

Show a token

View API token with this GET request:

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

Request parameters

URL parameterTypeRequiredLimitationsDetails
token_idstringyes

Request Body

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

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

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

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b1aaaaaaaaa",
    "name": "First token",
    "status": "unpause",
    "created_at": "2024-04-12T11:27:53.000000Z",
    "scopes": [
      "email_full"
    ]
  }
}

Error

Response Code: 404 Not Found

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

import 'dotenv/config';
import { MailerSend, Token} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const token = new Token()
  .setName("Token name")
  .setDomainId("domain_id")
  .setScopes([
    "email_full",
    "domains_read",
    "domains_full",
    "activity_read",
    "activity_full",
    "analytics_read",
    "analytics_full",
    "tokens_full",
  ]);

mailerSend.token.create(token)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

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 parameterTypeRequiredLimitationsDetails
namestringyesMax: 50
domain_idstringyes
scopesarrayyes
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",
     "email_verification_read",
     "email_verification_full",
     "inbounds_full",
     "recipients_read",
     "recipients_full"
   ]

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 parameters

URL parameterTypeRequiredLimitationsDetails
token_idstringyes

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

import 'dotenv/config';
import { MailerSend} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.token.updateSettings("token_id", {
  status: "pause",
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

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 parameterTypeRequiredLimitationsDetails
statusstringnopause, unpause

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b1aaaaaaaaa",
    "name": "First token",
    "status": "unpause",
    "created_at": "2024-04-12T11:27:53.000000Z",
    "scopes": [
      "email_full"
    ]
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Change token name a token

Change an API token name with this PUT request:

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

Request parameters

URL parameterTypeRequiredLimitationsDetails
token_idstringyes

Request Body

{
    "name": "new name"
}

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

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

$mailersend->token->changeName('token_id', 'new name');

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
namestringnomax length 50 chars

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b1aaaaaaaaa",
    "name": "First token",
    "status": "unpause",
    "created_at": "2024-04-12T11:27:53.000000Z",
    "scopes": [
      "email_full"
    ]
  }
}

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 parameterTypeRequiredLimitationsDetails
token_idstringyes
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TokenParams;

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

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

More examplesopen in new window

import 'dotenv/config';
import { MailerSend} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.token.delete("token_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

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
Last Updated: