Sender Identities
Easily manage email sender identities with MailerSend's API. Add, update, delete and retrieve a list of sender identities.
Get a list of sender identities
Retrieve information about sender identities with this GET request:
GET https://api.mailersend.com/v1/identitiesRequest parameters
| Query parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
domain_id | string | no | ||
page | int | no | Min: 1 | |
limit | int | no | Min: 10, Max: 100 | Default: 25 |
query | string | no | Filter by email address. | |
order_by | string | no | email, created_at, verified_at | Default: created_at |
order | string | no | asc, desc | Default: asc |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->getAll($domainId = 'domainId', $page = 1, $limit = 10);Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": [
{
"id": "7nxe3yjmeq28vp0k",
"email": "john@test.com",
"name": "John Doe",
"reply_to_email": null,
"reply_to_name": null,
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
],
"links": {
"first": "https://api.mailersend.com/v1/identities?page=1",
"last": "https://api.mailersend.com/v1/identities?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"page": null,
"active": false
},
{
"url": "https://api.mailersend.com/v1/identities?page=1",
"label": "1",
"page": 1,
"active": true
},
{
"url": null,
"label": "Next »",
"page": null,
"active": false
}
],
"path": "https://api.mailersend.com/v1/identities",
"per_page": 25,
"to": 1,
"total": 1
}
}Error
Response Code: 422 Unprocessable EntitySee - Validation errors
Get a single sender identity
If you want to retrieve a single sender identity, use this GET request:
GET https://api.mailersend.com/v1/identities/{identity_id}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
identity_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->find('identityId');Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "john@test.com",
"name": "John Doe",
"reply_to_email": null,
"reply_to_name": null,
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Error
Response Code: 404 Not FoundGet a single sender identity by email
If you want to retrieve a single sender identity by email, use this GET request:
GET https://api.mailersend.com/v1/identities/email/{email}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
email | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->findByEmail('email');Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "john@test.com",
"name": "John Doe",
"reply_to_email": null,
"reply_to_name": null,
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Error
Response Code: 404 Not FoundAdd a sender identity
If you want to add a new sender identity from which you can send emails without having to verify a domain, use this POST request:
POST https://api.mailersend.com/v1/identitiesRequest body
{
"domain_id": "7nxe3yjmeq28vp0k",
"email": "pedro@test.com",
"name": "Pedro Doe",
"personal_note": "Hi Pedro, please confirm this email by clicking on the link below.",
"reply_to_name": "Test Doe",
"reply_to_email": "test@test.com",
"add_note": true
}Request Parameters
JSON parameters are provided in dot notation
| JSON Parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
domain_id | string | yes | ||
name | string | no | Max 191 characters. | |
email | string | yes | Max 320 characters, unique per domain. Domains marked as unavailable or with a DMARC p=reject policy are rejected. | |
reply_to_email | string | no | Max 320 characters. Domains marked as unavailable are rejected. | Required when reply_to_name is set. |
reply_to_name | string | no | Max 191 characters. | |
add_note | boolean | no | ||
personal_note | string | no | Max 250 characters. HTML is stripped. Can't contain links, domain names or email addresses. |
Responses
| Response Key | Type | Details |
|---|---|---|
| data | object | Identity object created. |
Valid
Response Code: 201 CREATED
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "pedro@test.com",
"name": "Pedro Doe",
"reply_to_email": "test@test.com",
"reply_to_name": "Test Doe",
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Invalid
Response Code: 422 Unprocessable EntitySee - Validation errors
Identity limit error
Response Code: 403 Forbidden
Response Headers:
content-type: application/json{
"message": "You've reached the maximum sender identity limit. Upgrade to add more identities."
}Update a sender identity
If you want to update the information of an existing sender identity, use this PUT request:
PUT https://api.mailersend.com/v1/identities/{identity_id}Request body
{
"name": "Pedro Doe",
"reply_to_name": "Test Doe",
"reply_to_email": "test@test.com"
}Request Parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
identity_id | string | yes |
JSON parameters are provided in dot notation
| JSON Parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
name | string | no | Max 191 characters. | |
reply_to_email | string | no | Max 320 characters. Domains marked as unavailable are rejected. | Required when reply_to_name is set. |
reply_to_name | string | no | Max 191 characters. | |
add_note | boolean | no | Whether to add personal_note to the verification email. | |
personal_note | string | no | Max 250 characters. HTML is stripped. Can't contain links, domain names or email addresses. |
Responses
| Response Key | Type | Details |
|---|---|---|
| data | object | Identity object updated. |
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "pedro@test.com",
"name": "Pedro Doe",
"reply_to_email": "test@test.com",
"reply_to_name": "Test Doe",
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Invalid
Response Code: 422 Unprocessable EntitySee - Validation errors
Premium feature error
Response Code: 403 Forbidden
Response Headers:
content-type: application/json{
"message": "Sender identity is a premium feature. Please Upgrade your plan to update sender identity."
}Error
Response Code: 404 Not FoundUpdate a sender identity by email
If you want to update the information of an existing sender identity by email, use this PUT request:
PUT https://api.mailersend.com/v1/identities/email/{email}Request body
{
"name": "Pedro Doe",
"reply_to_name": "Test Doe",
"reply_to_email": "test@test.com"
}Request Parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
email | string | yes |
JSON parameters are provided in dot notation
| JSON Parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
name | string | no | Max 191 characters. | |
reply_to_email | string | no | Max 320 characters. Domains marked as unavailable are rejected. | Required when reply_to_name is set. |
reply_to_name | string | no | Max 191 characters. | |
add_note | boolean | no | Whether to add personal_note to the verification email. | |
personal_note | string | no | Max 250 characters. HTML is stripped. Can't contain links, domain names or email addresses. |
Responses
| Response Key | Type | Details |
|---|---|---|
| data | object | Identity object updated. |
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "pedro@test.com",
"name": "Pedro Doe",
"reply_to_email": "test@test.com",
"reply_to_name": "Test Doe",
"is_verified": false,
"resends": 0,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Invalid
Response Code: 422 Unprocessable EntitySee - Validation errors
Error
Response Code: 404 Not FoundDelete a sender identity
If you want to delete a sender identity, use this DELETE request:
DELETE https://api.mailersend.com/v1/identities/{identity_id}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
identity_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->delete('identityId');Responses
Valid
Response Code: 204 No ContentError
Response Code: 404 Not FoundDelete a sender identity by email
If you want to delete a sender identity by email, use this DELETE request:
DELETE https://api.mailersend.com/v1/identities/email/{email}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
email | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->deleteByEmail('email');Responses
Valid
Response Code: 202 AcceptedError
Response Code: 404 Not FoundResend a sender identity verification
If you want to resend the verification email for a sender identity, use this POST request:
POST https://api.mailersend.com/v1/identities/{identity_id}/resendRequest parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
identity_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->resend('identityId');Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "john@test.com",
"name": "John Doe",
"reply_to_email": null,
"reply_to_name": null,
"is_verified": false,
"resends": 1,
"add_note": false,
"personal_note": null,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}Error
Response Code: 404 Not FoundIdentity limit error
Response Code: 403 Forbidden
Response Headers:
content-type: application/json{
"message": "You've reached the maximum sender identity limit. Upgrade to add more identities."
}Resend limit error
Response Code: 429 Too Many Requests
Response Headers:
content-type: application/json{
"message": "Limit of max 3 emails was reached. Contact support if you need additional help."
}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.
Inbound routing
Easily manage inbound emails with MailerSend's Inbound Routing API endpoint. Retrieve, add, update and delete inbound routes.