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	Min: `1`
`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

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

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

mailerSend.token.list({ page: 1, limit: 25 })
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, TokensBuilder

ms = MailerSendClient()

request = (TokensBuilder()
          .page(1)
          .limit(25)
          .build_tokens_list())

response = ms.tokens.list_tokens(request)

More examples

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

public void getTokens() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        TokenListResponse response = ms.tokens()
            .page(1)
            .limit(25)
            .getTokens();

        for (Token token : response.tokens) {
            System.out.println(token.id);
            System.out.println(token.name);
            System.out.println(token.status);
        }

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

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"],
      "domain": {
        "id": "yjm4ej",
        "name": "example.org",
        "created_at": "2020-06-10 10:09:50",
        "updated_at": "2020-06-10 10:09:50"
      }
    },
    {
      "id": "481c8fdf59036be3f102b1ee6052e0f50a42051702dc5c820c1753d1752adc41ba5b12aaaaaaaaa",
      "name": "Second token",
      "status": "unpause",
      "created_at": "2024-04-17T08:40:13.000000Z",
      "scopes": ["domains_read", "analytics_full"],
      "domain": {
        "id": "yjm4ej",
        "name": "example.org",
        "created_at": "2020-06-10 10:09:50",
        "updated_at": "2020-06-10 10:09:50"
      }
    }
  ],
  "links": {
    "first": "https://api.mailersend.com/v1/token?page=1",
    "last": "https://api.mailersend.com/v1/token?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://api.mailersend.com/v1/token?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://api.mailersend.com/v1/token",
    "per_page": 25,
    "to": 2,
    "total": 2
  }
}

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

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

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

mailerSend.token.single("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_get())

response = ms.tokens.get_token(request)

More examples

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

public void getToken() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        Token token = ms.tokens().getToken("token id");

        System.out.println(token.id);
        System.out.println(token.name);
        System.out.println(token.status);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

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"],
    "domain": {
      "id": "yjm4ej",
      "name": "example.org",
      "created_at": "2020-06-10 10:09:50",
      "updated_at": "2020-06-10 10:09:50"
    }
  }
}

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, TokenScopeType } from "mailersend";

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

const token = new Token("Token name", [
  TokenScopeType.EMAIL_FULL,
  TokenScopeType.DOMAINS_READ,
  TokenScopeType.DOMAINS_FULL,
  TokenScopeType.ACTIVITY_READ,
  TokenScopeType.ACTIVITY_FULL,
  TokenScopeType.ANALYTICS_READ,
  TokenScopeType.ANALYTICS_FULL,
  TokenScopeType.TOKENS_FULL,
], "domain_id");

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("Your API token");
    
    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_client = Mailersend::Client.new('your_mailersend_token')

ms_tokens = Mailersend::Tokens.new(ms_client)
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	Must be a verified domain ID
`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_read",
     "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",
    "scopes": [
      "email_full",
      "domains_read"
    ],
    "has_full": false,
    "has_only_sending": false,
    "domain": {
      "id": "dle1krod2jvn8gwm",
      "name": "testname.com",
      "dkim": null,
      "spf": null,
      "mx": null,
      "tracking": null,
      "is_verified": false,
      "is_dns_active": false,
      "is_trial_domain": false,
      "domain_settings": {
        "send_paused": false,
        "send_paused_by_downgrade": false,
        "track_clicks": true,
        "track_opens": true,
        "track_opens_pixel_on_top": false,
        "track_unsubscribe": false,
        "track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
        "track_unsubscribe_html_enabled": false,
        "track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
        "track_unsubscribe_plain_enabled": false,
        "track_content": false,
        "custom_tracking_enabled": false,
        "custom_tracking_subdomain": "email",
        "return_path_subdomain": "mta",
        "inbound_routing_enabled": false,
        "inbound_routing_subdomain": "inbound",
        "precedence_bulk": false,
        "ignore_duplicated_recipients": false
      },
      "can": {
        "manage": true
      },
      "totals": [],
      "is_being_verified": false,
      "is_custom_links_available": false,
      "needs_dkim_migration": false,
      "dkim_deprecation_date": "February 1, 2027"
    },
    "preview": "mlsn.4f2a9c",
    "expires_at": null
  }
}

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 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 updateToken() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        // true to pause it, false to unpause it
        Token token = ms.tokens().updateToken("token id", true);

        System.out.println(token.name);
        System.out.println(token.status);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_tokens = Mailersend::Tokens.new(ms_client)
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"],
    "domain": {
      "id": "yjm4ej",
      "name": "example.org",
      "created_at": "2020-06-10 10:09:50",
      "updated_at": "2020-06-10 10:09:50"
    }
  }
}

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

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

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

mailerSend.token.update("token_id", { name: "New token name" })
  .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")
          .name("new name")
          .build_token_update_name())

response = ms.tokens.update_token_name(request)

More examples

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

public void updateTokenName() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        Token token = ms.tokens().updateToken("token id", "New Name", null);

        System.out.println(token.name);
        System.out.println(token.status);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examples

Request parameters

JSON parameters are provided in dot notation.

JSON parameter	Type	Required	Limitations	Details
`name`	string	required without `status`	max length 50 chars
`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"],
    "domain": {
      "id": "yjm4ej",
      "name": "example.org",
      "created_at": "2020-06-10 10:09:50",
      "updated_at": "2020-06-10 10:09:50"
    }
  }
}

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.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.tokens.Token;

public void CreateToken() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");
    
    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_client = Mailersend::Client.new('your_mailersend_token')

ms_tokens = Mailersend::Tokens.new(ms_client)
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