MailerSend Developers

# Domains

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

# Get a list of domains

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

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

# Request parameters

URL parameter Type Required Limitations Details
page int no
limit int no Min: 10, Max: 100 Default: 25
verified bool no

# 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,
      "has_not_queued_messages": false,
      "not_queued_messages_count": 0,
      "domain_settings": {
        "send_paused": false,
        "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": false,
        "custom_tracking_subdomain": "email"
      },
      "created_at": "2020-06-10 10:09:48",
      "updated_at": "2020-06-10 10:09:48"
    }
	],
  "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 - Validations errors

# Get a single domain

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

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

# Request parameters

URL parameter Type Required Limitations Details
domain_id string yes

# Responses

# Valid

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

{
  "data": {
    "id": "yjm4ej",
    "name": "example.org",
    "dkim": true,
    "spf": true,
    "mx": false,
    "tracking": false,
    "is_verified": true,
    "is_cname_verified": false,
    "is_dns_active": true,
    "is_cname_active": false,
    "is_tracking_allowed": false,
    "has_not_queued_messages": false,
    "not_queued_messages_count": 0,
    "domain_settings": {
      "send_paused": false,
      "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": false,
      "custom_tracking_subdomain": "email"
    },
    "created_at": "2020-06-10 10:09:50",
    "updated_at": "2020-06-10 10:09:50"
  }
}

# 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": "rp_subdomain",
  "custom_tracking_subdomain": "ct_subdomain",
  "inbound_routing_subdomain": "ir_subdomain"
}

# Request Parameters

JSON parameters are provided in dot notation

JSON Parameter Type Required Limitations Details
name string yes Must be unique, lowercase, can't be an unavailable domain and resolvable.
return_path_subdomain string no Must be alphanumeric.
custom_tracking_subdomain string no Must be alphanumeric.
inbound_routing_subdomain string no Must be alphanumeric.

# Responses

Response Key Type Details
data object Domain 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,
    "domain_settings": {
      "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_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"
    },
    "can": {
      "manage": true
    },
    "totals": []
  }
}

# Invalid

Response Code: 422 Unprocessable Entity

See - Validations 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 parameter Type Required Limitations Details
domain_id string yes

# Responses

# Valid

Response Code: 200 OK

# Error

Response Code: 404 Not Found

# Get recipients for a domain

If you want to have 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 parameter Type Required Limitations Details
domain_id string yes
Query parameter Type Required Limitations Details
page int no
limit int no Min: 10, Max: 100 Default: 25

# 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": "https:\/\/www.mailersend.io\/api\/v1\/domains\/7qvdnq?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/www.mailersend.io\/api\/v1\/recipients",
    "per_page": 25,
    "to": 3,
    "total": 3
  }
}

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Update domain settings

If you want to update a 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"
}

# Request parameters

URL parameter Type Required Limitations Details
domain_id string yes

JSON parameters are provided in dot notation

JSON Body Parameter Type Required Limitations Details
send_paused bool No
track_clicks bool no
track_opens bool no
track_unsubscribe bool no
track_content bool no
track_unsubscribe_html string no
track_unsubscribe_plain string no
custom_tracking_enabled bool no
custom_tracking_subdomain string no

# 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,
    "has_not_queued_messages": false,
    "not_queued_messages_count": 0,
    "domain_settings": {
      "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"
    },
    "created_at": "2020-06-10 10:09:52",
    "updated_at": "2020-06-10 10:09:52"
  }
}

# Error

Response Code: 422 Unprocessable Entity

See - Validations errors

# Get DNS Records

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

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

# Request Parameters

URL Parameter Type Required Limitations Details
domain_id string yes

# 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": {
      "hostname": "mlsend._domainkey.testname.com",
      "type": "TXT",
      "value": "v=DKIM1;t=s;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCv9y0EE38P8bpwNnvTRZvxnQkpe7hmv9clRGG8Vj+g3\/JTVh0Q\/4EOrgn29CO\/8ByRGzc9t\/IAQ0pevN0yXOKOLt8Gng67dzqp2hA1IKEBHPwRZjv30ROSjpknDcmnJSVK2KO3sI7lxzQo73fwuwm9WVbXUJpBJG8yQftwibkj+QIDAQAB"
    },
    "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"
    }
  }
}

# Invalid

Response Code: 404 Not Found

# Verify a domain

If you want to verify a domain, use this GET request:

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

# Request Parameters

URL Parameter Type Required Limitations Details
domain_id string yes

# 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
Last updated: 9/1/2021, 3:08:20 PM

← Email →