Domains
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
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
2
3
{
"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",
"precedence_bulk": false
},
"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
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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 parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes |
Responses
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"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",
"precedence_bulk": false
},
"created_at": "2020-06-10 10:09:50",
"updated_at": "2020-06-10 10:09:50"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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"
}
2
3
4
5
6
Request Parameters
JSON parameters are provided in dot notation
JSON Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
name | string | yes | Must be unique and lowercase. Domain must be available 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
2
3
{
"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",
"precedence_bulk": false
},
"can": {
"manage": true
},
"totals": []
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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 parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes |
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 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
2
3
{
"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
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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
}
2
3
4
5
6
7
8
9
10
11
12
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 | ||
precedence_bulk | bool | 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",
"precedence_bulk": false
},
"created_at": "2020-06-10 10:09:52",
"updated_at": "2020-06-10 10:09:52"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Error
Response Code: 422 Unprocessable Entity
See - Validation errors
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
Request Parameters
URL Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes |
Responses
Valid
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"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"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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 Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes |
Responses
Valid
Domain verified:
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"message": "The domain is verified.",
"data": {
"dkim": true,
"spf": true,
"mx": true,
"tracking": false,
"cname": true,
"rp_cname": true
}
}
2
3
4
5
6
7
8
9
10
11
Domain not verified:
Response Code: 200 OK
Response Headers:
Content-Type: application/json
2
3
{
"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
}
}
2
3
4
5
6
7
8
9
10
11
Invalid
Response Code: 404 Not Found