Tokens

Create and manage API tokens for MailerSend Email API. Securely authenticate and authorize access to your account with ease.

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 parameter	Type	Required	Limitations	Details
`page`	`int`	no
`limit`	`int`	no	Min: `10`, Max: `100`	Default: `25`

Request Body

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

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

$mailersend->token->getAll();

More examples

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 parameter	Type	Required	Limitations	Details
`token_id`	`string`	yes

Request Body

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

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

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

More examples

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 examples

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 examples

from mailersend import MailerSendClient, TokensBuilder

ms = MailerSendClient()

request = (TokensBuilder()
          .name("My API Token")
          .scopes(["email_full", "analytics_read"])
          .domain_id("domain-id")
          .build_token_create())

response = ms.tokens.create_token(request)

More examples

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 examples

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 examples

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 examples

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations
`name`	`string`	yes	Max: `50`
`domain_id`	`string`	no
`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",
     "email_verification_read",
     "email_verification_full",
     "inbounds_full",
     "recipients_read",
     "recipients_full",
     "sender_identity_read",
     "sender_identity_full",
     "users_read",
     "users_full",
     "smtp_users_read",
     "smtp_users_full",
     "dmarc_monitoring_read",
     "dmarc_monitoring_full",
     "blocklist_monitoring_read",
     "blocklist_monitoring_full",
     "whatsapp_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}

Request parameters

URL parameter	Type	Required	Limitations	Details
`token_id`	`string`	yes

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 examples

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 examples

from mailersend import MailerSendClient, TokensBuilder

ms = MailerSendClient()

# Pause token
request = (TokensBuilder()
          .token_id("token-id")
          .status("pause")
          .build_token_update())

response = ms.tokens.update_token(request)

# Unpause token
request = (TokensBuilder()
          .token_id("token-id")
          .status("unpause")
          .build_token_update())

response = ms.tokens.update_token(request)

More examples

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",
	}

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

More examples

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 examples

require "mailersend-ruby"

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

More examples

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations	Details
`name`	`string`	required without `status`	Max: `50`
`status`	`string`	no	`pause`, `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

Change an API token name with this PUT request:

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

Request parameters

URL parameter	Type	Required	Limitations	Details
`token_id`	`string`	yes

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 examples

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations	Details
`name`	string	no	max 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 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 examples

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 examples

from mailersend import MailerSendClient, TokensBuilder

ms = MailerSendClient()

request = (TokensBuilder()
          .token_id("token-id")
          .build_token_delete())

response = ms.tokens.delete_token(request)

More examples

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 examples

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 examples

require "mailersend-ruby"

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

More examples

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 404 Not Found

On this page