MailerSend
Email API

Domains

Discover how to easily manage your email domains using MailerSend's Domains API endpoint. Get a list of domains or retrieve a single domain in just a few clicks.

Get information about your domain names, their account verification statuses, activity statistics, and history.

Get a list of domains

If you want to retrieve information about multiple domains, use this GET request:

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

Request parameters

Query parameterTypeRequiredLimitationsDetails
pageintnoMin: 1
limitintnoMin: 10, Max: 100Default: 25
verifiedboolno
use MailerSend\MailerSend;

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

$mailersend->domain->getAll($page = 1, $limit = 10, $verified = true);

More examples

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

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

mailerSend.email.domain.list()
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .page(1)
          .limit(25)
          .build_list_request())

response = ms.domains.list_domains(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()

	options := &mailersend.ListDomainOptions{
		Page:  1,
		Limit: 25,
	}

	_, _, err := ms.Domain.List(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.Domain;
import com.mailersend.sdk.domains.DomainsList;
import com.mailersend.sdk.exceptions.MailerSendException;

public void DomainsList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("token");
    
    try {
        
        DomainsList list = ms.domains().getDomains();
        
        for (Domain domain : list.domains) {
            
            System.out.println(domain.id);
            System.out.println(domain.name);
        }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.list

More examples

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "data": [
    {
      "id": "1jreeo",
      "name": "example.org",
      "dkim": true,
      "spf": true,
      "tracking": false,
      "is_verified": true,
      "is_cname_verified": false,
      "is_dns_active": true,
      "is_cname_active": false,
      "is_tracking_allowed": false,
      "domain_stats": {
        "total": 1200,
        "queued": 0,
        "sent": 1200,
        "rejected": 0,
        "delivered": 1180
      },
      "has_not_queued_messages": false,
      "not_queued_messages_count": 0,
      "domain_settings": {
        "send_paused": false,
        "track_clicks": true,
        "track_opens": true,
        "track_opens_pixel_on_top": false,
        "track_unsubscribe": true,
        "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": true,
        "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
      },
      "is_sending_paused": false,
      "created_at": "2020-06-10 10:09:48",
      "updated_at": "2020-06-10 10:09:48",
      "totals": []
    }
  ],
  "links": {
    "first": "http:\/\/www.mailersend.io\/api\/v1\/domains?page=1",
    "last": "http:\/\/www.mailersend.io\/api\/v1\/domains?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/www.mailersend.io\/api\/v1\/domains",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Get a single domain

If you want to retrieve information about a single domain name, use this GET request:

GET https://api.mailersend.com/v1/domains/{domain_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
domain_idstringyes
use MailerSend\MailerSend;

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

$mailersend->domain->find('domain_id');

More examples

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

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

mailerSend.email.domain.single("domain_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .build_get_request())

response = ms.domains.get_domain(request)
print(f"Domain: {response['data']['name']}")

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"

	_, _, err := ms.Domain.Get(ctx, domainID)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.Domain;
import com.mailersend.sdk.exceptions.MailerSendException;

public void SingleDomain() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        Domain domain = ms.domains().getDomain("domain id");
        
        System.out.println(domain.id);
        System.out.println(domain.name);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.single(domain_id: "idofdomain12412")

More examples

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "data": {
    "id": "yjm4ej",
    "name": "example.org",
    "dkim": true,
    "spf": true,
    "tracking": false,
    "is_verified": true,
    "is_cname_verified": false,
    "is_dns_active": true,
    "is_cname_active": false,
    "is_tracking_allowed": false,
    "domain_stats": {
      "total": 1200,
      "queued": 0,
      "sent": 1200,
      "rejected": 0,
      "delivered": 1180
    },
    "has_not_queued_messages": false,
    "not_queued_messages_count": 0,
    "domain_settings": {
      "send_paused": false,
      "track_clicks": true,
      "track_opens": true,
      "track_opens_pixel_on_top": false,
      "track_unsubscribe": true,
      "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": true,
      "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
    },
    "is_sending_paused": false,
    "created_at": "2020-06-10 10:09:50",
    "updated_at": "2020-06-10 10:09:50",
    "totals": {
      "sent": 1200,
      "delivered": 1180,
      "soft_bounced": 12,
      "hard_bounced": 8
    }
  }
}

Error

Response Code: 404 Not Found

Add a domain

If you want to add a new domain, use this POST request:

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

Request body

{
    "name": "example.com",
    "return_path_subdomain": "rpsubdomain",
    "custom_tracking_subdomain": "ctsubdomain",
    "inbound_routing_subdomain": "irsubdomain"
}
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\DomainParams;

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

$domainParams = (new DomainParams('domainName'))
                    ->setReturnPathSubdomain('returnPath')
                    ->setCustomTrackingSubdomain('customTracking')
                    ->setInboundRoutingSubdomain('inboundRouting');

$mailersend->domain->create($domainParams);

More examples

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

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

const domain = new Domain(
  "example.com",
  "rpsubdomain",
  "ctsubdomain",
  "irsubdomain",
)

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

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_name("mydomain.com")
          .return_path_subdomain("rp")
          .custom_tracking_subdomain("ct")
          .inbound_routing_subdomain("ir")
          .build_create_request())

response = ms.domains.create_domain(request)
print(f"Created domain with ID: {response['data']['id']}")

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

	options := &mailersend.CreateDomainOptions{
		Name: "domain.test",
	}

	_, _, err := ms.Domain.Create(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.Domain;
import com.mailersend.sdk.exceptions.MailerSendException;

public void AddDomain() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        Domain domain = ms.domains().addDomainBuilder().addDomain("domain to add");
        
        System.out.println(domain.id);
        System.out.println(domain.name);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.add(name: "example.com")

More examples

Request Parameters

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
namestringyesMust be unique and lowercase. Domain must be available and resolvable. Must not start with www..
return_path_subdomainstringnoMust be alphanumeric.
custom_tracking_subdomainstringnoMust be alphanumeric.
inbound_routing_subdomainstringnoMust be alphanumeric.

Responses

Response KeyTypeDetails
dataobjectDomain object created.

Valid

Response Code: 201 CREATED
Response Headers:
	content-type: application/json
{
  "data": {
    "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"
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

Delete a domain

If you want to delete a domain name, use this DELETE request:

DELETE https://api.mailersend.com/v1/domains/{domain_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
domain_idstringyes
use MailerSend\MailerSend;

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

$mailersend->domain->delete('domain_id');

More examples

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

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

mailerSend.email.domain.delete("domain_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .build_delete_request())

response = ms.domains.delete_domain(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"

	_, err := ms.Domain.Delete(ctx, domainID)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

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

public void DeleteDomain() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        boolean domainDeleted = ms.domains().deleteDomain("domain id");
        
        System.out.println("Domain deleted: ".contains(String.valueOf(domainDeleted)));
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.delete(domain_id: "idofdomain12412")

More examples

Responses

Valid

Response Code: 204 OK

Error

Response Code: 404 Not Found

Get recipients for a domain

If you want to retrieve information (creation date, update date, deletion date) about the recipients for a domain name, use this GET request:

GET https://api.mailersend.com/v1/domains/{domain_id}/recipients

Request parameters

URL parameterTypeRequiredLimitationsDetails
domain_idstringyes
Query parameterTypeRequiredLimitationsDetails
pageintno
limitintnoMin: 10, Max: 100Default: 25
use MailerSend\MailerSend;

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

$mailersend->domain->recipients($domainId = 'domain_id', $page = 1, $limit = 10);

More examples

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

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

mailerSend.email.domain.recipients("domain_id", {
  page: 1,
  limit: 10
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .page(1)
          .limit(25)
          .build_recipients_request())

response = ms.domains.get_domain_recipients(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"
	
	options := &mailersend.GetRecipientsOptions{
	 	DomainID: domainID,
	 	Page:     1,
	 	Limit:    25,
	}
	
	_, _, err := ms.Domain.GetRecipients(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.DomainRecipientsList;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.util.ApiRecipient;

public void ReceipientsPerDomain() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        DomainRecipientsList list = ms.domains().getDomainRecipients("domaion id");
        
        for (ApiRecipient recipient : list.recipients) {
            
            System.out.println(recipient.email);
        }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.recipients(domain_id: "idofdomain12412")

More examples

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "data": [
    {
      "id": "5ee0b174b251345e407c92dc",
      "email": "dsanford@example.net",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    },
    {
      "id": "5ee0b174b251345e407c92dd",
      "email": "konopelski.nina@example.com",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    },
    {
      "id": "5ee0b174b251345e407c92de",
      "email": "hester.howe@example.net",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    }
  ],
  "links": {
    "first": "https:\/\/www.mailersend.io\/api\/v1\/domains\/7qvdnq\/recipients?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "current_page_url": "https:\/\/www.mailersend.io\/api\/v1\/domains\/7qvdnq\/recipients?page=1",
    "from": 1,
    "path": "https:\/\/www.mailersend.io\/api\/v1\/domains\/7qvdnq\/recipients",
    "per_page": 25,
    "to": 3
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Update domain settings

If you want to update the domain name settings, use this PUT request:

PUT https://api.mailersend.com/v1/domains/{domain_id}/settings

Request Body

{
    "send_paused": true,
    "track_clicks": true,
    "track_opens": true,
    "track_unsubscribe": true,
    "track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe<\/a><\/p>",
    "track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
    "track_content": true,
    "custom_tracking_enabled": true,
    "custom_tracking_subdomain": "email",
    "precedence_bulk": false,
    "ignore_duplicated_recipients": false
}
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\DomainSettingsParams;

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

$domainSettingsParam = (new DomainSettingsParams())
                            ->setSendPaused(true)
                            ->setTrackClicks(true)
                            ->setTrackOpens(false)
                            ->setTrackUnsubscribe(false)
                            ->setTrackUnsubscribeHtmlEnabled(true)
                            ->setTrackUnsubscribePlainEnabled(true)
                            ->setTrackContent(true)
                            ->setTrackUnsubscribeHtml('<p>Click here to <a href="{{unsubscribe}}">unsubscribe</a></p>')
                            ->setTrackUnsubscribePlain('Click here to unsubscribe: {{unsubscribe}}')
                            ->setCustomTrackingEnabled(true)
                            ->setCustomTrackingSubdomain('email')
                            ->setPrecedenceBulk(false)
                            ->setIgnoreDuplicatedRecipients(false);

$mailersend->domain->domainSettings($domainId = 'domain_id', $domainSettingsParam);

More examples

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

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

mailerSend.email.domain.updateSettings("domain_id", {
  send_paused: true,
  track_clicks: true,
  track_opens: true,
  track_unsubscribe: true,
  track_unsubscribe_html: "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
  track_unsubscribe_html_enabled: true,
  track_unsubscribe_plain: "Click here to unsubscribe: {{unsubscribe}}",
  track_unsubscribe_plain_enabled: true,
  track_content: true,
  custom_tracking_enabled: true,
  custom_tracking_subdomain: "subdomain",
  precedence_bulk: false,
  ignore_duplicated_recipients: false,
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .send_paused(False)
          .track_clicks(True)
          .track_opens(True)
          .track_unsubscribe(True)
          .track_content(True)
          .custom_tracking_enabled(True)
          .custom_tracking_subdomain_setting("email")
          .precedence_bulk(False)
          .build_update_settings_request())

response = ms.domains.update_domain_settings(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"
	
	options := &mailersend.DomainSettingOptions{
		DomainID:                   domainID,
		SendPaused:                 mailersend.Bool(false),
		TrackClicks:                mailersend.Bool(true),
		TrackOpens:                 mailersend.Bool(true),
		TrackUnsubscribe:           mailersend.Bool(true),
		TrackUnsubscribeHTML:       "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
		TrackUnsubscribePlain:      "Click here to unsubscribe: {{unsubscribe}}",
		TrackContent:               mailersend.Bool(true),
		CustomTrackingEnabled:      mailersend.Bool(true),
		CustomTrackingSubdomain:    "email",
		PrecedenceBulk:             mailersend.Bool(false),
		IgnoreDuplicatedRecipients: mailersend.Bool(false),
	}
	
	_, _, err := ms.Domain.Update(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.Domain;
import com.mailersend.sdk.exceptions.MailerSendException;

public void UpdateDomainSettings() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        Domain domain = ms.domains().updateDomainSettingsBuilder()
            .customnTrackingEnabled(true)
            .sendPaused(false)
            .precedenceBulk(false)
            .ignoreDuplicatedRecipients(false)
            .updateDomain("domain id");
        
        System.out.println(domain.domainSettings.customTrackingEnabled);
        System.out.println(domain.domainSettings.sendPaused);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.settings(
  domain_id: "idofdomain12412",
  send_paused: false,
  track_clicks: true,
  track_opens: true,
  track_unsubscribe: false,
  track_unsubscribe_html: '<p>Click here to <a href="{{unsubscribe}}">unsubscribe</a></p>',
  track_unsubscribe_plain: "Click here to unsubscribe: {{unsubscribe}}",
  track_content: true,
  custom_tracking_enabled: true,
  custom_tracking_subdomain: "email",
  precedence_bulk: false
)

More examples

Request parameters

URL parameterTypeRequiredLimitationsDetails
domain_idstringyes

JSON parameters are provided in dot notation

JSON Body ParameterTypeRequiredLimitationsDetails
send_pausedboolNo
track_clicksboolno
track_opensboolno
track_unsubscribeboolno
track_contentboolno
track_unsubscribe_htmlstringnoMust be valid HTML and contain the {{unsubscribe}} variable.
track_unsubscribe_html_enabledboolno
track_unsubscribe_plainstringnoMust contain the {{unsubscribe}} variable.
track_unsubscribe_plain_enabledboolno
custom_tracking_enabledboolno
custom_tracking_subdomainstringnoMust be alphanumeric.
precedence_bulkboolno
ignore_duplicated_recipientsboolno

Responses

Valid

Response Code: 200 OK
{
  "data": {
    "id": "dq3wdj",
    "name": "example.org",
    "dkim": true,
    "spf": true,
    "tracking": false,
    "is_verified": true,
    "is_cname_verified": true,
    "is_dns_active": true,
    "is_cname_active": true,
    "is_tracking_allowed": true,
    "domain_stats": {
      "total": 1200,
      "queued": 0,
      "sent": 1200,
      "rejected": 0,
      "delivered": 1180
    },
    "has_not_queued_messages": false,
    "not_queued_messages_count": 0,
    "domain_settings": {
      "send_paused": true,
      "track_clicks": true,
      "track_opens": true,
      "track_opens_pixel_on_top": false,
      "track_unsubscribe": true,
      "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": true,
      "custom_tracking_enabled": true,
      "custom_tracking_subdomain": "email",
      "return_path_subdomain": "mta",
      "inbound_routing_enabled": false,
      "inbound_routing_subdomain": "inbound",
      "precedence_bulk": false,
      "ignore_duplicated_recipients": false
    },
    "is_sending_paused": true,
    "created_at": "2020-06-10 10:09:52",
    "updated_at": "2020-06-10 10:09:52",
    "totals": []
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Content tracking not available on your plan

Response Code: 403 Forbidden
Response Headers:
	content-type: application/json
{
  "message": "Your plan doesn't allow this action, upgrade your plan to get all available features."
}

The request includes track_content, but your plan does not include content tracking.

Response Code: 403 Forbidden
Response Headers:
	content-type: application/json
{
  "message": "To disable the unsubscribe link, please contact support."
}

The request includes track_unsubscribe, but the unsubscribe link is enforced on your account.

Custom tracking on a trial domain

Response Code: 403 Forbidden
Response Headers:
	content-type: application/json
{
  "message": "Custom tracking cannot be enabled on trial domains."
}

The request includes custom_tracking_enabled for a trial domain.

Get DNS Records

If you want to retrieve the domain's DNS records, use this GET request:

GET https://api.mailersend.com/v1/domains/{domain_id}/dns-records

DKIM is now two CNAME records

MailerSend signs with 2048-bit DKIM keys, published as two CNAME records: dkim_ms1 and dkim_ms2. Both must be added to your DNS zone.

If your domain was verified with the older single DKIM record, publish these two records to migrate. Support for the legacy record ends on 1 February 2027, and there is no need to remove it in the meantime.

Request Parameters

URL ParameterTypeRequiredLimitationsDetails
domain_idstringyes
use MailerSend\MailerSend;

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

$mailersend->domain->getDnsRecords('domain_id');

More examples

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

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

mailerSend.email.domain.dns("domain_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .build_dns_records_request())

response = ms.domains.get_domain_dns_records(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"

	_, _, err := ms.Domain.GetDNS(ctx, domainID)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.Domain;
import com.mailersend.sdk.domains.DomainDnsAttribute;
import com.mailersend.sdk.domains.DomainDnsRecords;
import com.mailersend.sdk.exceptions.MailerSendException;

public void DomainDnsRecords() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        DomainDnsRecords records = ms.domains().getDomainDnsRecords("domain id");
        
        printDomainDnsAttribute(records.spf);
        printDomainDnsAttribute(records.dkimMs1);
        printDomainDnsAttribute(records.dkimMs2);
        printDomainDnsAttribute(records.customTracking);
        printDomainDnsAttribute(records.returnPath);
        printDomainDnsAttribute(records.inboundRouting);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

private void printDomainDnsAttribute(DomainDnsAttribute attribute) {
    
    System.out.println(attribute.hostname);
    System.out.println(attribute.type);
    System.out.println(attribute.value);
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.dns(domain_id: "idofdomain12412")

More examples

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "data": {
    "id": "dle1krod2jvn8gwm",
    "spf": {
      "hostname": "testname.com",
      "type": "TXT",
      "value": "v=spf1 include:_spf.mailersend.net ip6:fd43:c0d1:c090::\/48 -all"
    },
    "dkim_ms1": {
      "hostname": "ms1._domainkey.testname.com",
      "type": "CNAME",
      "value": "ms1._domainkey.mailersend.net"
    },
    "dkim_ms2": {
      "hostname": "ms2._domainkey.testname.com",
      "type": "CNAME",
      "value": "ms2._domainkey.mailersend.net"
    },
    "dkim": {
      "hostname": null,
      "type": null,
      "value": null
    },
    "return_path": {
      "hostname": "mta.testname.com",
      "type": "CNAME",
      "value": "mailersend.net"
    },
    "custom_tracking": {
      "hostname": "email.testname.com",
      "type": "CNAME",
      "value": "links.mailersend.net"
    },
    "inbound_routing": {
      "hostname": "inbound.testname.com",
      "type": "MX",
      "value": "inbound.mailersend.net",
      "priority": "10"
    }
  }
}

The legacy dkim record is still returned for backward compatibility, with all values set to null.

Invalid

Response Code: 404 Not Found

Get verification status

If you want to retrieve the verification status for a domain, use this GET request:

GET https://api.mailersend.com/v1/domains/{domain_id}/verify

Request Parameters

URL ParameterTypeRequiredLimitationsDetails
domain_idstringyes
use MailerSend\MailerSend;

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

$mailersend->domain->verify('domain_id');

More examples

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

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

mailerSend.email.domain.verify("domain_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, DomainsBuilder

ms = MailerSendClient()

request = (DomainsBuilder()
          .domain_id("domain-id")
          .build_verification_request())

response = ms.domains.get_domain_verification_status(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"

	_, _, err := ms.Domain.Verify(ctx, domainID)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.domains.DomainVerificationStatus;
import com.mailersend.sdk.exceptions.MailerSendException;

public void VerifyDomain() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("api token");
    
    try {
        
        DomainVerificationStatus status = ms.domains().verifyDomain("domain id");
        
        System.out.println(status.message);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

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

ms_domains = Mailersend::Domains.new(ms_client)
ms_domains.verify(domain_id: "idofdomain12412")

More examples

Responses

Valid

Domain verified:

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "message": "The domain is verified.",
  "data": {
    "dkim": true,
    "spf": true,
    "mx": true,
    "tracking": false,
    "cname": true,
    "rp_cname": true
  }
}

Domain not verified:

Response Code: 200 OK
Response Headers:
	content-type: application/json
{
  "message": "The domain was not verified, please check your DNS records and try again.",
  "data": {
    "dkim": false,
    "spf": false,
    "mx": false,
    "tracking": false,
    "cname": false,
    "rp_cname": false
  }
}

Invalid

Response Code: 404 Not Found

Analytics

Track the performance of your transactional emails with MailerSend's Analytics API endpoint. Discover opens by country, email activity and more.

Sender Identities

Easily manage email sender identities with MailerSend's API. Add, update, delete and retrieve a list of sender identities.

On this page

Get a list of domainsResponsesValidErrorGet a single domainResponsesValidErrorAdd a domainResponsesValidInvalidDelete a domainResponsesValidErrorGet recipients for a domainResponsesValidErrorUpdate domain settingsResponsesValidErrorContent tracking not available on your planUnsubscribe link enforced on your accountCustom tracking on a trial domainGet DNS RecordsResponsesValidInvalidGet verification statusResponsesValidInvalid