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:10:11",
"updated_at": "2020-06-10 10:10:11"
}
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
# Recipients (/api/v1/email/recipients)
Fetch the email addresses of recipients and other relevant information.
## Get recipients [#get-recipients]
Retrieve the email addresses of recipients using this `GET` request:
```http
GET https://api.mailersend.com/v1/recipients
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `page` | `int` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->get(null, $limit = 100, $page = 3);
// Or for a specific domain
$mailersend->recipients->get('domain_id', $limit = 100, $page = 3);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.list({
domain_id: "domain_id",
limit: 10,
})
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
request = (RecipientsBuilder()
.domain_id("domain-id")
.build_recipients_list_request())
response = ms.recipients.list_recipients(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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.ListRecipientOptions{
//DomainID: domainID,
Page: 1,
Limit: 25,
}
_, _, err := ms.Recipient.List(ctx, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.util.ApiRecipient;
import com.mailersend.sdk.util.ApiRecipientsList;
public void GetRecipients() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
ApiRecipientsList list = ms.recipients().getRecipients();
for (ApiRecipient recipient : list.recipients) {
System.out.println(recipient.id);
System.out.println(recipient.email);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_recipients = Mailersend::Recipients.new
ms_recipients.list(page: 1, limit: 10)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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\/recipients?page=1",
"last": "https:\/\/www.mailersend.io\/api\/v1\/recipients?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https:\/\/www.mailersend.io\/api\/v1\/recipients",
"per_page": 25,
"to": 3,
"total": 3
}
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Get a single recipient [#get-a-single-recipient]
Retrieve the information of a single recipient and its domain using this `GET` request:
```http
GET https://api.mailersend.com/v1/recipients/{recipient_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| -------------- | -------- | -------- | ----------- | ------- |
| `recipient_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->find('recipient_id');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.single("recipient_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
request = (RecipientsBuilder()
.recipient_id("recipient-id")
.build_recipient_get_request())
response = ms.recipients.get_recipient(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
recipientID := "recipient-id"
_, _, err := ms.Recipient.Get(ctx, recipientID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.Recipient;
public void GetSingleRecipient() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
Recipient recipient = ms.recipients().getRecipient("recipient id");
System.out.println(recipient.email);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_recipients = Mailersend::Recipients.new
ms_recipients.single(recipient_id: "id124")
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "5ee0b185b251345e407c938e",
"email": "hauck.sincere@example.net",
"created_at": "2020-06-10 10:10:13",
"updated_at": "2020-06-10 10:10:13",
"deleted_at": "",
"emails": [],
"domain": {
"id": "2j6xej",
"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": "Click here to 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:10:13",
"updated_at": "2020-06-10 10:10:13"
}
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
## Delete a recipient [#delete-a-recipient]
Delete the information of a single recipient and its domain using this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/recipients/{recipient_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
| URL parameter | Type | Required | Limitations | Details |
| -------------- | -------- | -------- | ----------- | ------- |
| `recipient_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->delete('recipient_id');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.delete("recipient_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
request = (RecipientsBuilder()
.recipient_id("recipient-id")
.build_recipient_delete_request())
response = ms.recipients.delete_recipient(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
recipientID := "recipient-id"
_, err := ms.Recipient.Delete(ctx, recipientID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.MailerSendResponse;
public void DeleteRecipient() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
MailerSendResponse response = ms.recipients().deleteRecipient("recipient id");
System.out.println(response.responseStatusCode);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_recipients = Mailersend::Recipients.new
ms_recipients.delete(recipient_id: "id124")
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-2]
#### Valid [#valid-2]
```http
Response Code: 204 No Content
Response Body: [EMPTY]
```
#### Error [#error-2]
```http
Response Code: 404 Not Found
```
## Get recipients from a suppression list [#get-recipients-from-a-suppression-list]
### Blocklist [#blocklist]
Retrieve the recipients in a blocklist of an account or domain by passing the blocklist ID with this `GET` request:
```http
GET https://api.mailersend.com/v1/suppressions/blocklist
```
#### Request parameters \[!toc] [#request-parameters-toc-3]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `10` |
| `page` | `int` | no | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->blocklist->getAll('domain_id', 15);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { BlockListType, MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.blockList(
{ domain_id: "domain_id", },
BlockListType.BLOCK_LIST
)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
request = (RecipientsBuilder()
.domain_id("domain-id")
.build_suppression_list_request())
response = ms.recipients.list_blocklist(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
listOptions := &mailersend.SuppressionOptions{
DomainID: "domain-id",
Page: 1,
Limit: 25,
}
// List Block List Recipients
_, _, err := ms.Suppression.ListBlockList(ctx, listOptions)
if err != nil {
log.Fatal(err)
}
// List Hard Bounces
_, _, _ = ms.Suppression.ListHardBounces(ctx, listOptions)
// List Spam Complaints
_, _, _ = ms.Suppression.ListSpamComplaints(ctx, listOptions)
// List Unsubscribes
_, _, _ = ms.Suppression.ListUnsubscribes(ctx, listOptions)
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;
public void GetRecipientsFromSuppressionList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
BlocklistListResponse blocklist = ms.recipients().suppressions().getBlocklist();
for (BlocklistItem item : blocklist.items) {
System.out.println(item.id);
System.out.println(item.pattern);
System.out.println(item.type);
}
SuppressionList hardBounces = ms.recipients().suppressions().getHardBounces();
for (SuppressionItem item : hardBounces.items) {
System.out.println(item.id);
System.out.println(item.recipient.email);
}
SuppressionList spamComplaints = ms.recipients().suppressions().getSpamComplaints();
for (SuppressionItem item : spamComplaints.items) {
System.out.println(item.id);
System.out.println(item.recipient.email);
}
SuppressionList unsubscribes = ms.recipients().suppressions().getUnsubscribes();
for (SuppressionItem item : unsubscribes.items) {
System.out.println(item.id);
System.out.println(item.recipient.email);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_suppressions = Mailersend::Suppressions.new
// List from Blocklist
ms_suppressions.get_from_blocklist(domain_id: "xxx2241ll")
// List from Hard Bounces
ms_suppressions.get_hard_bounces(domain_id: "xxx2241ll")
// List from Spam Complaints
ms_suppressions.get_spam_complaints(domain_id: "xxx2241ll")
// List from Unsubscribers
ms_suppressions.get_unsubscribes(domain_id: "xxx2241ll")
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Responses [#responses-3]
| Response key | Type | Details |
| --------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data.*` | `object[]` | Array of recipients in the blocklist. |
| `data.*.domain` | `object` | Includes data of the domain related to the blocklist. When this property is `null`, the blocklist is attached to an account instead of a domain. |
#### Valid [#valid-3]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f0176881bf3d1fe618daae",
"type": "pattern",
"pattern": ".*@example.net",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
},
"created_at": "2021-07-14T07:04:01.298000Z",
"updated_at": "2021-07-14T07:04:01.298000Z"
}
]
}
```
#### Error [#error-3]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Hard Bounces [#hard-bounces]
Retrieve the hard bounced recipients of an account or domain by passing its ID with this `GET` request:
```http
GET https://api.mailersend.com/v1/suppressions/hard-bounces
```
#### Request parameters \[!toc] [#request-parameters-toc-4]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `10` |
| `page` | `int` | no | | |
#### Responses [#responses-4]
| Response key | Type | Details |
| ------------------------- | ---------- | ------------------------------------- |
| `data.*` | `object[]` | Array of hard bounces. |
| `data.*.recipient` | `object` | Recipient related to the hard bounce. |
| `data.*.recipient.domain` | `object` | Domain related to the hard bounce. |
#### Valid [#valid-4]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f0176881bf3d1fe618dab0",
"reason": "Unknown reason",
"created_at": "2021-06-29T07:04:01.298000Z",
"recipient": {
"id": "60f0176881bf3d1fe618daaf",
"email": "test@example.com",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
```
#### Error [#error-4]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Spam Complaints [#spam-complaints]
Retrieve the recipients who have made a spam complaint for an account or domain by passing its ID with this `GET` request:
```http
GET https://api.mailersend.com/v1/suppressions/spam-complaints
```
#### Request parameters \[!toc] [#request-parameters-toc-5]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `10` |
| `page` | `int` | no | | |
### Responses [#responses-5]
| Response key | Type | Details |
| ------------------------- | ---------- | ---------------------------------------- |
| `data.*` | `object[]` | Array of spam complaints. |
| `data.*.recipient` | `object` | Recipient related to the spam complaint. |
| `data.*.recipient.domain` | `object` | Domain related to the spam complaint. |
#### Valid [#valid-5]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f0176981bf3d1fe618dab4",
"created_at": "2021-06-29T07:04:01.298000Z",
"recipient": {
"id": "60f0176881bf3d1fe618dab3",
"email": "pmcdermott@example.net",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
```
#### Error [#error-5]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Unsubscribes [#unsubscribes]
Retrieve the unsubscribed recipients for an account or domain by passing its ID with this `GET` request:
```http
GET https://api.mailersend.com/v1/suppressions/unsubscribes
```
#### Request parameters \[!toc] [#request-parameters-toc-6]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `10` |
| `page` | `int` | no | | |
### Responses [#responses-6]
| Response key | Type | Details |
| ------------------------- | ---------- | ------------------------------------- |
| `data.*` | `object[]` | Array of unsubscribes. |
| `data.*.recipient` | `object` | Recipient related to the unsubscribe. |
| `data.*.recipient.domain` | `object` | Domain related to the unsubscribe. |
#### Valid [#valid-6]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f0176881bf3d1fe618dab2",
"reason": "NEVER_SIGNED",
"readable_reason": "I never signed up for this mailing list",
"recipient": {
"id": "60f0176881bf3d1fe618dab1",
"email": "taya86@example.com",
"created_at": "2021-06-29T07:04:01.298000Z",
"updated_at": "2021-06-29T07:04:01.298000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
},
"created_at": "2021-06-29T07:04:01.298000Z"
}
]
}
```
#### Error [#error-6]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### On Hold List [#on-hold-list]
Retrieve on hold recipients for an account or domain by passing its ID with this `GET` request:
```http
GET https://api.mailersend.com/v1/suppressions/on-hold-list
```
#### Request parameters \[!toc] [#request-parameters-toc-7]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `10` |
| `page` | `int` | no | | |
### Responses [#responses-7]
| Response key | Type | Details |
| ------------------------- | ---------- | ---------------------------------------- |
| `data.*` | `object[]` | Array of on hold list. |
| `data.*.recipient` | `object` | Recipient on hold. |
| `data.*.recipient.domain` | `object` | Domain related to the on hold recipient. |
#### Valid [#valid-7]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "64c760a33e2db0f6340f4710",
"created_at": "2023-07-15T19:22:37.579000Z",
"on_hold_until": "2023-07-18T19:22:37.579000Z",
"email": "shanna.fadel@example.net",
"recipient": {
"id": "64c760a33e2db0f6340f470f",
"email": "shanna.fadel@example.net",
"created_at": "2023-07-15T19:22:37.579000Z",
"updated_at": "2023-07-15T19:22:37.579000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailerlite.com",
"created_at": "2023-07-31T07:18:59.000000Z",
"updated_at": "2023-07-31T07:19:23.000000Z"
}
}
}
]
}
```
#### Error [#error-7]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Add recipients to a suppression list [#add-recipients-to-a-suppression-list]
### Blocklist [#blocklist-1]
Add a recipient to a blocklist with this `POST` request:
```http
POST https://api.mailersend.com/v1/suppressions/blocklist
```
#### Request Body \[!toc] [#request-body-toc]
```json
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
],
"patterns": [
".*@example.com"
]
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\BlocklistParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$params = (new BlocklistParams())
->setDomainId('domain_id')
->setRecipients(['recipient_one', 'recipient_two'])
->setPatterns(['pattern_one', 'pattern_two']);
$mailersend->blocklist->create($params);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { BlockListType, MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.blockRecipients({
domain_id: 'domain_id',
recipients: [
"test@example.com"
]
}, BlockListType.BLOCK_LIST)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
# Using specific emails
request = (RecipientsBuilder()
.domain_id("domain-id")
.recipients(["blocked@example.com", "spam@example.com"])
.build_suppression_add_request())
response = ms.recipients.add_to_blocklist(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
package main
import (
"context"
"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()
// Add Recipient to Block List
createSuppressionBlockOptions := &mailersend.CreateSuppressionBlockOptions{
DomainID: "domain-id",
Recipients: []string{"test@example.com"},
Patterns: []string{".*@example.com"},
}
_, _, _ = ms.Suppression.CreateBlock(ctx, createSuppressionBlockOptions)
// Add Recipient to Hard Bounces
createSuppressionHardBounceOptions := &mailersend.CreateSuppressionOptions{
DomainID: "domain-id",
Recipients: []string{"test@example.com"},
}
_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionHardBounceOptions)
// Add Recipient to Spam Complaints
createSuppressionSpamComplaintsOptions := &mailersend.CreateSuppressionOptions{
DomainID: "domain-id",
Recipients: []string{"test@example.com"},
}
_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionSpamComplaintsOptions)
// Add Recipient to Unsubscribes
createSuppressionUnsubscribesOptions := &mailersend.CreateSuppressionOptions{
DomainID: "domain-id",
Recipients: []string{"test@example.com"},
}
_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionUnsubscribesOptions)
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;
public void AddRecipientsToSuppressionList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
// blocklist
ms.recipients().suppressions().addBuilder().pattern(".*@example.com");
ms.recipients().suppressions().addBuilder().recipient("test@example.com");
BlocklistItem[] items = ms.recipients().suppressions().addBuilder().addToBlocklist();
for (BlocklistItem item : items) {
System.out.println(item.id);
}
// hard bounces
ms.recipients().suppressions().addBuilder().recipient("test@example.com");
ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
SuppressionList list = ms.recipients().suppressions().addBuilder().addRecipientsToHardBounces();
for (SuppressionItem item : list.items) {
System.out.println(item.id);
}
// spam complaints
ms.recipients().suppressions().addBuilder().recipient("test@example.com");
ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
list = ms.recipients().suppressions().addBuilder().addRecipientsToSpamComplaints();
for (SuppressionItem item : list.items) {
System.out.println(item.id);
}
// unsubscribes
ms.recipients().suppressions().addBuilder().recipient("test@example.com");
ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
list = ms.recipients().suppressions().addBuilder().addRecipientsToUnsubscribes();
for (SuppressionItem item : list.items) {
System.out.println(item.id);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_suppressions = Mailersend::Suppressions.new
// Add Recipient to Block List using recipients
ms_suppressions.add_to_blocklist(domain_id: "xxx2241ll", recipients: ["blocked@client.com"])
// Add Recipient to Block List using patterns
ms_suppressions.add_to_blocklist(domain_id: "xxx2241ll", patterns: ["*@client.com"])
// Add Recipient to Hard Bounces
ms_suppressions.add_to_hard_bounces(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])
// Add Recipient to Spam Complaints
ms_suppressions.add_to_spam_complaints(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])
// Add Recipient to Unsubscribes
ms_suppressions.add_to_unsubscribers(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc-8]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | ---------------------------------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `recipients[]` | `string[]` | no | If `patterns` is not defined, this property is required. | |
| `recipients.*` | `string` | yes | Must be an email. | |
| `patterns[]` | `string[]` | no | If `recipients` is not defined, this property is required. | |
| `patterns.*` | `string` | yes | | |
### Responses [#responses-8]
| Response key | Type | Details |
| ------------ | ---------- | ----------------------------------- |
| `data.*` | `object[]` | Array of blocklist entries created. |
#### Valid [#valid-8]
```http
Response Code: 201 Created
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f198790542d97fb66dfe52",
"type": "exact",
"pattern": "test@example.com",
"created_at": "2021-07-16T14:32:25.457000Z",
"updated_at": "2021-07-16T14:32:25.457000Z"
},
{
"id": "60f198790542d97fb66dfe53",
"type": "pattern",
"pattern": ".*@example.com",
"created_at": "2021-07-16T14:32:25.476000Z",
"updated_at": "2021-07-16T14:32:25.476000Z"
}
]
}
```
#### Error [#error-8]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Hard Bounces [#hard-bounces-1]
Add a hard bounce for one or more recipients with this `POST` request:
```http
POST https://api.mailersend.com/v1/suppressions/hard-bounces
```
#### Request Body \[!toc] [#request-body-toc-1]
```json
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
```
#### Request parameters \[!toc] [#request-parameters-toc-9]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | ----------------- | ------- |
| `domain_id` | `string` | yes | | |
| `recipients[]` | `string[]` | yes | | |
| `recipients.*` | `string` | yes | Must be an email. | |
### Responses [#responses-9]
| Response key | Type | Details |
| ---------------------- | ---------- | ------------------------------------- |
| `data.*` | `object[]` | Array of hard bounces created. |
| `data.*.recipient` | `object` | Recipient related to the hard bounce. |
| `data.*.domain.domain` | `object` | Domain related to the hard bounce. |
#### Valid [#valid-9]
```http
Response Code: 201 Created
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f1a0195c14080bbc606293",
"reason": null,
"created_at": "2021-07-16T15:04:57.939000Z",
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-16T15:04:57.907000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
```
#### Error [#error-9]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Spam Complaints [#spam-complaints-1]
Add a spam complaint for one or more recipients with this `POST` request:
```http
POST https://api.mailersend.com/v1/suppressions/spam-complaints
```
#### Request Body \[!toc] [#request-body-toc-2]
```json
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
```
#### Request parameters \[!toc] [#request-parameters-toc-10]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | ----------------- | ------- |
| `domain_id` | `string` | yes | | |
| `recipients[]` | `string[]` | yes | | |
| `recipients.*` | `string` | yes | Must be an email. | |
### Responses [#responses-10]
| Response key | Type | Details |
| ------------------------- | ---------- | ---------------------------------------- |
| `data.*` | `object[]` | Array of spam complaints created. |
| `data.*.recipient` | `object` | Recipient related to the spam complaint. |
| `data.*.recipient.domain` | `object` | Domain related to the spam complaint. |
#### Valid [#valid-10]
```http
Response Code: 201 Created
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f1a9fa33d68f023f2d3972",
"created_at": "2021-07-16T15:47:06.280000Z",
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-16T15:47:06.244000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
}
}
]
}
```
#### Error [#error-10]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
### Unsubscribes [#unsubscribes-1]
Set one or more recipients as unsubscribed with this `POST` request:
```http
POST https://api.mailersend.com/v1/suppressions/unsubscribes
```
#### Request Body \[!toc] [#request-body-toc-3]
```json
{
"domain_id": "83gwk2j7zqz1nxyd",
"recipients": [
"test@example.com"
]
}
```
#### Request parameters \[!toc] [#request-parameters-toc-11]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | ----------------- | ------- |
| `domain_id` | `string` | yes | | |
| `recipients[]` | `string[]` | yes | | |
| `recipients.*` | `string` | yes | Must be an email. | |
### Responses [#responses-11]
| Response key | Type | Details |
| ------------------------- | ---------- | ------------------------------------- |
| `data.*` | `object[]` | Array of unsubscribe entries created. |
| `data.*.recipient` | `object` | Recipient related to the unsubscribe. |
| `data.*.recipient.domain` | `object` | Domain related to the unsubscribe. |
#### Valid [#valid-11]
```http
Response Code: 201 Created
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "60f53a20506faf239d471ff2",
"reason": null,
"readable_reason": null,
"recipient": {
"id": "60f1a0195c14080bbc606292",
"email": "test@example.com",
"created_at": "2021-07-16T15:04:57.888000Z",
"updated_at": "2021-07-19T08:38:56.243000Z",
"deleted_at": "",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "mailersend.com",
"created_at": "2021-07-15T11:04:44.000000Z",
"updated_at": "2021-07-15T11:04:45.000000Z"
}
},
"created_at": "2021-07-19T08:38:56.283000Z"
}
]
}
```
#### Error [#error-11]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Delete recipients from a suppression list [#delete-recipients-from-a-suppression-list]
### Blocklist [#blocklist-2]
Delete one or more blocklist entries with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/suppressions/blocklist
```
#### Request Body \[!toc] [#request-body-toc-4]
To delete specific entries:
```json
{
"ids": [
"60f198790542d97fb66dfe52",
"60f198790542d97fb66dfe53"
]
}
```
To delete all entries:
```json
{
"all": true
}
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
// Delete specific instances
$mailersend->blocklist->delete(['id_one', 'id_two']);
// or delete all
$mailersend->blocklist->delete(null, true);
// You can also specify the domain
$mailersend->blocklist->delete(['id'], false, 'domain_id');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { BlockListType, MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.recipient.delBlockListRecipients(
["recipient_id", "recipient_id"],
BlockListType.BLOCK_LIST
)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, RecipientsBuilder
ms = MailerSendClient()
# Delete specific entries by IDs
request = (RecipientsBuilder()
.domain_id("domain-id")
.ids(["recipient-id-1", "recipient-id-2"])
.build_suppression_delete_request())
response = ms.recipients.delete_from_blocklist(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
package main
import (
"context"
"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"
// Delete All {type}
// mailersend.BlockList
// mailersend.HardBounces
// mailersend.SpamComplaints
// mailersend.Unsubscribes
_, _ = ms.Suppression.DeleteAll(ctx, domainID, mailersend.Unsubscribes)
// Delete
deleteSuppressionOption := &mailersend.DeleteSuppressionOptions{
DomainID: domainID,
Ids: []string{"suppression-id"},
}
_, _ = ms.Suppression.Delete(ctx, deleteSuppressionOption, mailersend.Unsubscribes)
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;
public void DeleteRecipientsFromSuppressionList () {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
// delete from blocklist
BlocklistListResponse blocklist = ms.recipients().suppressions().getBlocklist();
if (blocklist.items.length == 0) {
fail();
}
String itemId = blocklist.items[0].id;
MailerSendResponse response = ms.recipients().suppressions().deleteBlocklistItems(new String[] { itemId });
System.out.println(response.responseStatusCode);
// delete from hard bounces
SuppressionList hardBounces = ms.recipients().suppressions().getHardBounces();
if (hardBounces.items.length == 0) {
fail();
}
itemId = hardBounces.items[0].id;
response = ms.recipients().suppressions().deleteHardBouncesItems(new String[] { itemId });
System.out.println(response.responseStatusCode);
// delete from spam complaints
SuppressionList spamComplaints = ms.recipients().suppressions().getSpamComplaints();
if (spamComplaints.items.length == 0) {
fail();
}
itemId = spamComplaints.items[0].id;
response = ms.recipients().suppressions().deleteSpamComplaintsItems(new String[] { itemId });
System.out.println(response.responseStatusCode);
// delete from unsubscribes
SuppressionList unsubscribes = ms.recipients().suppressions().getUnsubscribes();
if (unsubscribes.items.length == 0) {
fail();
}
itemId = unsubscribes.items[0].id;
response = ms.recipients().suppressions().deleteUnsubscribesItems(new String[] { itemId });
System.out.println(response.responseStatusCode);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_suppressions = Mailersend::Suppressions.new
// Delete from Block List
ms_suppressions.delete_from_blocklist(domain_id: 'yourdomainid', ids: ["xxx2241ll"])
// Delete from Hard Bounces
ms_suppressions.delete_from_hard_bounces(domain_id: 'yourdomainid', ids: ["xxx2241ll"])
// Delete from Spam Complaints
ms_suppressions.delete_from_spam_complaints(domain_id: 'yourdomainid', ids: ["xxx2241ll"])
// Delete from Unsubscribes
ms_suppressions.delete_from_unsubscribers(domain_id: 'yourdomainid', ids: ["xxx2241ll"])
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc-12]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | --------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `ids` | `string[]` | no | Required if `all` is not defined. | |
| `all` | `boolean` | no | Required if `ids` is not defined. | |
### Responses [#responses-12]
#### Valid [#valid-12]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-12]
```http
Response Code: 422 Unprocessable Entity
```
```json
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
```
*See - [Validation errors](/../../general#validation-errors)*
### Hard Bounces [#hard-bounces-2]
Delete one or more hard bounces from recipients by passing the hard bounces IDs with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/suppressions/hard-bounces
```
#### Request Body \[!toc] [#request-body-toc-5]
To delete specific entries:
```json
{
"ids": [
"60d0563fd4fb3212e2065522",
"60ae0999c3da7c275f3b5589"
]
}
```
To delete all entries:
```json
{
"all": true
}
```
#### Request parameters \[!toc] [#request-parameters-toc-13]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | --------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `ids` | `string[]` | no | Required if `all` is not defined. | |
| `all` | `boolean` | no | Required if `ids` is not defined. | |
### Responses [#responses-13]
#### Valid [#valid-13]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-13]
```http
Response Code: 422 Unprocessable Entity
```
```json
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
```
*See - [Validation errors](/../../general#validation-errors)*
### Spam Complaints [#spam-complaints-2]
Delete one or more spam complaints from recipients by providing the spam complaint IDs with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/suppressions/spam-complaints
```
#### Request Body \[!toc] [#request-body-toc-6]
To delete specific entries:
```json
{
"ids": [
"60d32115d14907786d7fdd42",
"60ae0999c3da7c275f3b558e"
]
}
```
To delete all entries:
```json
{
"all": true
}
```
#### Request parameters \[!toc] [#request-parameters-toc-14]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | --------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `ids` | `string[]` | no | Required if `all` is not defined. | |
| `all` | `boolean` | no | Required if `ids` is not defined. | |
### Responses [#responses-14]
#### Valid [#valid-14]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-14]
```http
Response Code: 422 Unprocessable Entity
```
```json
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
```
*See - [Validation errors](/../../general#validation-errors)*
### Unsubscribes [#unsubscribes-2]
Delete one or more unsubscribe entries from recipients by passing the unsubscribe IDs with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/suppressions/unsubscribes
```
#### Request Body \[!toc] [#request-body-toc-7]
To delete specific entries:
```json
{
"ids": [
"60d3169d8dc7b007f356d142",
"60ae0999c3da7c275f3b558b"
]
}
```
To delete all entries:
```json
{
"all": true
}
```
#### Request parameters \[!toc] [#request-parameters-toc-15]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | --------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `ids` | `string[]` | no | Required if `all` is not defined. | |
| `all` | `boolean` | no | Required if `ids` is not defined. | |
### Responses [#responses-15]
#### Valid [#valid-15]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-15]
```http
Response Code: 422 Unprocessable Entity
```
```json
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
```
*See - [Validation errors](/../../general#validation-errors)*
### On Hold List [#on-hold-list-1]
Delete one or more recipient entries from on hold list by passing the on hold list IDs with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/suppressions/on-hold-list
```
#### Request Body \[!toc] [#request-body-toc-8]
To delete specific entries:
```json
{
"ids": [
"64c760a33e2db0f6340f4710",
"64c760a33e2db0f6340f470e"
]
}
```
To delete all entries:
```json
{
"all": true
}
```
#### Request parameters \[!toc] [#request-parameters-toc-16]
*JSON parameters are provided in dot notation.*
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | ---------- | -------- | --------------------------------- | ------- |
| `domain_id` | `string` | no | | |
| `ids` | `string[]` | no | Required if `all` is not defined. | |
| `all` | `boolean` | no | Required if `ids` is not defined. | |
### Responses [#responses-16]
#### Valid [#valid-16]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-16]
```http
Response Code: 422 Unprocessable Entity
```
```json
{
"message": "The given data was invalid.",
"errors": {
"ids.0": [
"The selected ids.0 is invalid."
],
"ids.1": [
"The selected ids.1 is invalid."
]
}
}
```
*See - [Validation errors](/../../general#validation-errors)*
# Sender Identities (/api/v1/email/sender-identity)
## Get a list of sender identities [#get-a-list-of-sender-identities]
Retrieve information about sender identities with this `GET` request:
```http
GET https://api.mailersend.com/v1/identities
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | ------------------------------------ | ------------------------ |
| `domain_id` | `string` | no | | |
| `page` | `int` | no | | |
| `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` | |
| `order` | `string` | no | `asc`, `desc` | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->getAll($domainId = 'domainId', $page = 1, $limit = 10);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.list()
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.domain_id("domain-id")
.build_list_request())
response = ms.identities.list_identities(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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.ListIdentityOptions{
DomainID: domainID,
Page: 1,
Limit: 25,
}
_, _, err := ms.Identity.List(ctx, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.identities.Identity;
import com.mailersend.sdk.identities.IdentitiesList;
import com.mailersend.sdk.exceptions.MailerSendException;
public void ListIdentities() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
IdentitiesList list = ms.identities().getIdentities("domain-id", 1, 25);
for (Identity identity : list.identities) {
System.out.println(identity.id);
System.out.println(identity.email);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.list
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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 [#error]
```http
Response Code: 404 Not Found
```
## Get a single sender identity [#get-a-single-sender-identity]
If you want to retrieve a single sender identity, use this `GET` request:
```http
GET https://api.mailersend.com/v1/identities/{identity_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `identity_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->find('identityId');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.single("identity_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.identity_id("identity-id")
.build_get_request())
response = ms.identities.get_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
identityID := "identity-id"
_, _, err := ms.Identity.Get(ctx, identityID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.identities.Identity;
import com.mailersend.sdk.exceptions.MailerSendException;
public void GetIdentity() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
Identity identity = ms.identities().getIdentity("identity-id");
System.out.println(identity.id);
System.out.println(identity.email);
System.out.println(identity.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.single(identity_id: 'idofidentity123')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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 [#error-1]
```http
Response Code: 404 Not Found
```
## Get a single sender identity by email [#get-a-single-sender-identity-by-email]
If you want to retrieve a single sender identity by email, use this `GET` request:
```http
GET https://api.mailersend.com/v1/identities/email/{email}
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `email` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->findByEmail('email');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.singleByEmail('email_address')
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```go
package main
import (
"context"
"os"
"log"
"time"
"github.com/mailersend/mailersend-go"
)
func main() {
// Create an instance of the mailersend client
ms := mailersend.NewMailersend(os.Getenv("MAILERSEND_API_KEY"))
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
_, _, err := ms.Identity.GetByEmail(ctx, "identity-email")
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```ruby
require "mailersend-ruby"
ms_client = Mailersend::Client.new('your_mailersend_token')
ms_sender_identity = Mailersend::SenderIdentity.new(ms_client)
ms_sender_identity.single_by_email(email: 'example@email.com')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-2]
#### Valid [#valid-2]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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 [#error-2]
```http
Response Code: 404 Not Found
```
## Add a sender identity [#add-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:
```http
POST https://api.mailersend.com/v1/identities
```
### Request body \[!toc] [#request-body-toc]
```json
{
"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
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SenderIdentity;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->create(
(new SenderIdentity('domainId', 'name', 'email'))
->setReplyToName("John Doe")
->setReplyToEmail("john@test.com"))
->setAddNote(true)
->setPersonalNote("Hi John, please use this token")
);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, Inbound, InboundFilterType } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const identity = new Identity()
.setDomainId('domain_id')
.setEmail('identity@yourdomain.com')
.setName('Name')
.setReplyToEmail('reply_identity@yourdomain.com')
.setReplyToName('Reply Name')
.setAddNote(false);
mailerSend.email.identity.create(identity)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.domain_id("domain-id")
.name("John Doe")
.email("john@yourdomain.com")
.reply_to_email("support@yourdomain.com")
.reply_to_name("Support Team")
.add_note(True)
.build_create_request())
response = ms.identities.create_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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.CreateIdentityOptions{
DomainID: "domain-id",
Name: "John Doe",
Email: "john@yourdomain.com",
ReplyToEmail: mailersend.String("support@yourdomain.com"),
ReplyToName: mailersend.String("Support Team"),
AddNote: mailersend.Bool(true),
}
_, _, err := ms.Identity.Create(ctx, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.identities.Identity;
import com.mailersend.sdk.exceptions.MailerSendException;
public void CreateIdentity() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
Identity identity = ms.identities().builder()
.domainId("domain-id")
.name("John Doe")
.email("john@yourdomain.com")
.replyToEmail("support@yourdomain.com")
.replyToName("Support Team")
.addNote(true)
.createIdentity();
System.out.println(identity.id);
System.out.println(identity.email);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.add(domain_id: 'idofdomain12412', name: 'yourname', email: 'youremail')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Request Parameters \[!toc] [#request-parameters-toc-3]
*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 | |
| `reply_to_email` | `string` | no | `Max` 320 characters. | 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. | |
### Responses [#responses-3]
| Response Key | Type | Details |
| ------------ | ------ | ------------------------ |
| data | object | Identity object created. |
#### Valid [#valid-3]
```http
Response Code: 201 CREATED
Response Headers:
content-type: application/json
```
```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": true,
"personal_note": "Hi Pedro, please confirm this email by clicking on the link below.",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}
```
#### Invalid [#invalid]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Update a sender identity [#update-a-sender-identity]
If you want to update the information of an existing sender identity, use this `PUT` request:
```http
PUT https://api.mailersend.com/v1/identities/{identity_id}
```
### Request body \[!toc] [#request-body-toc-1]
```json
{
"name": "Pedro Doe",
"reply_to_name": "Test Doe",
"reply_to_email": "test@test.com"
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SenderIdentity;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->update(
'identityId',
(new SenderIdentity('domainId', 'name', 'email'))
->setReplyToName("John Doe")
->setReplyToEmail("john@test.com"))
->setAddNote(true)
->setPersonalNote("Hi John, please use this token")
);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, Inbound, InboundFilterType } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const data = {
domain_id: 'string',
email: 'email@yourdomain.com',
name: 'name',
personal_note: 'Personal note',
reply_to_name: 'Reply Name',
reply_to_email: 'repy@yourdomain.com',
add_note: true,
};
mailerSend.email.identity.update('identity_id', data)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.identity_id("identity-id")
.name("Jane Doe")
.reply_to_email("support@yourdomain.com")
.reply_to_name("Support Team")
.add_note(True)
.build_update_request())
response = ms.identities.update_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
identityID := "identity-id"
options := &mailersend.UpdateIdentityOptions{
Name: mailersend.String("Jane Doe"),
ReplyToEmail: mailersend.String("support@yourdomain.com"),
ReplyToName: mailersend.String("Support Team"),
AddNote: mailersend.Bool(true),
}
_, _, err := ms.Identity.Update(ctx, identityID, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.identities.Identity;
import com.mailersend.sdk.exceptions.MailerSendException;
public void UpdateIdentity() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
Identity identity = ms.identities().builder()
.name("Jane Doe")
.replyToEmail("support@yourdomain.com")
.replyToName("Support Team")
.addNote(true)
.updateIdentity("identity-id");
System.out.println(identity.id);
System.out.println(identity.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.update(identity_id: 'idofidentity123', reply_to_email: 'replyemail', reply_to_name: 'replyname')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Request Parameters \[!toc] [#request-parameters-toc-4]
| 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. | Required when `reply_to_name` is set. |
| `reply_to_name` | `string` | no | `Max` 191 characters. | |
### Responses [#responses-4]
| Response Key | Type | Details |
| ------------ | ------ | ------------------------ |
| data | object | Identity object updated. |
#### Valid [#valid-4]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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": true,
"personal_note": "Hi Pedro, please confirm this email by clicking on the link below.",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}
```
#### Invalid [#invalid-1]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Update a sender identity by email [#update-a-sender-identity-by-email]
If you want to update the information of an existing sender identity by email, use this `PUT` request:
```http
PUT https://api.mailersend.com/v1/identities/email/{email}
```
### Request body \[!toc] [#request-body-toc-2]
```json
{
"name": "Pedro Doe",
"reply_to_name": "Test Doe",
"reply_to_email": "test@test.com"
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SenderIdentity;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->updateByEmail(
'email',
(new SenderIdentity('domainId', 'name', 'email'))
->setReplyToName("John Doe")
->setReplyToEmail("john@test.com"))
->setAddNote(true)
->setPersonalNote("Hi John, please use this token")
);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const data = {
name: 'Doe Jane',
reply_to_email: 'support@yourdomain.com',
reply_to_name: 'Support Team',
add_note: true,
};
mailerSend.email.identity.updateByEmail('support@yourdomain.com', data)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.email("support@yourdomain.com")
.name("Doe Jane")
.reply_to_email("support@yourdomain.com")
.reply_to_name("Support Team")
.add_note(True)
.build_update_by_email_request())
response = ms.identities.update_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
email := "support@yourdomain.com"
options := &mailersend.UpdateIdentityOptions{
Name: mailersend.String("Doe Jane"),
ReplyToEmail: mailersend.String("support@yourdomain.com"),
ReplyToName: mailersend.String("Support Team"),
AddNote: mailersend.Bool(true),
}
_, _, err := ms.Identity.UpdateByEmail(ctx, email, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.identities.Identity;
import com.mailersend.sdk.exceptions.MailerSendException;
public void UpdateIdentityByEmail() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
Identity identity = ms.identities().builder()
.email("support@yourdomain.com")
.name("Doe Jane")
.replyToEmail("support@yourdomain.com")
.replyToName("Support Team")
.addNote(true)
.updateIdentityByEmail();
System.out.println(identity.id);
System.out.println(identity.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.update_by_email(email: 'support@yourdomain.com', name: 'Doe Jane', reply_to_email: 'support@yourdomain.com', reply_to_name: 'Support Team', add_note: true)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Request Parameters \[!toc] [#request-parameters-toc-5]
| 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. | Required when `reply_to_name` is set. |
| `reply_to_name` | `string` | no | `Max` 191 characters. | |
### Responses [#responses-5]
| Response Key | Type | Details |
| ------------ | ------ | ------------------------ |
| data | object | Identity object updated. |
#### Valid [#valid-5]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```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": true,
"personal_note": "Hi Pedro, please confirm this email by clicking on the link below.",
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}
```
#### Invalid [#invalid-2]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Delete a sender identity [#delete-a-sender-identity]
If you want to delete a sender identity, use this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/identities/{identity_id}
```
### Request parameters \[!toc] [#request-parameters-toc-6]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `identity_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->delete('identityId');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.delete("identity_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.identity_id("identity-id")
.build_delete_request())
response = ms.identities.delete_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
identityID := "identity-id"
_, _, err := ms.Identity.Delete(ctx, identityID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
public void DeleteIdentity() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
ms.identities().deleteIdentity("identity-id");
System.out.println("Identity deleted successfully");
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.delete(identity_id: 'idofidentity123')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-6]
#### Valid [#valid-6]
```http
Response Code: 204 No Content
```
#### Error [#error-3]
```http
Response Code: 404 Not Found
```
## Delete a sender identity by email [#delete-a-sender-identity-by-email]
If you want to delete a sender identity by email, use this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/identities/email/{email}
```
### Request parameters \[!toc] [#request-parameters-toc-7]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `email` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->deleteByEmail('email');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.deleteByEmail('email_address')
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.email("support@yourdomain.com")
.build_delete_by_email_request())
response = ms.identities.delete_identity_by_email(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
email := "support@yourdomain.com"
_, _, err := ms.Identity.DeleteByEmail(ctx, email)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
public void DeleteIdentityByEmail() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
ms.identities().deleteIdentityByEmail("support@yourdomain.com");
System.out.println("Identity deleted successfully");
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_client = Mailersend::Client.new('your_mailersend_token')
ms_sender_identity = Mailersend::SenderIdentity.new(ms_client)
ms_sender_identity.delete_by_email(email: 'example@email.com')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-7]
#### Valid [#valid-7]
```http
Response Code: 202 Accepted
```
#### Error [#error-4]
```http
Response Code: 404 Not Found
```
## Resend a sender identity verification [#resend-a-sender-identity-verification]
If you want to resend the verification email for a sender identity, use this `POST` request:
```http
POST https://api.mailersend.com/v1/identities/{identity_id}/resend
```
### Request parameters \[!toc] [#request-parameters-toc-8]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `identity_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->senderIdentity->resend('identityId');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.identity.resend("identity_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, IdentityBuilder
ms = MailerSendClient()
request = (IdentityBuilder()
.identity_id("identity-id")
.build_resend_request())
response = ms.identities.resend_identity(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
identityID := "identity-id"
_, _, err := ms.Identity.Resend(ctx, identityID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
public void ResendIdentity() {
MailerSend ms = new MailerSend();
ms.setToken("api token");
try {
ms.identities().resendIdentity("identity-id");
System.out.println("Identity verification resent successfully");
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_sender_identity = Mailersend::SenderIdentity.new
ms_sender_identity.resend(identity_id: 'idofidentity123')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-8]
#### Valid [#valid-8]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "7nxe3yjmeq28vp0k",
"email": "john@test.com",
"name": "John Doe",
"reply_to_email": null,
"reply_to_name": null,
"is_verified": false,
"resends": 1,
"domain": {
"id": "7nxe3yjmeq28vp0k",
"name": "test.com",
"created_at": "2022-11-29T10:43:22.000000Z",
"updated_at": "2022-11-29T10:43:32.000000Z"
}
}
}
```
#### Error [#error-5]
```http
Response Code: 404 Not Found
```
# SMTP relay (/api/v1/email/smtp-relay)
Use Simple Mail Transfer Protocol (SMTP) when you want to quickly send emails using a reliable Internet standard. Our SMTP relay service takes care of your email delivery so you don’t have to manage an email server.
## Basic usage [#basic-usage]
[Enable SMTP on your Domain screen](https://www.mailersend.com/help/smtp-relay) and input the details into your SMTP client. Please refer to the documentation of your SMTP client for instructions on the exact way to set it up.
Your client must support TLS security via port `587`.
### Tracing back SMTP messages to use with the API [#tracing-back-smtp-messages-to-use-with-the-api]
Whenever a message is successfully parsed and queued in our system, you will get a similar response to this:
```
250 Message queued as 61eec2dc16ae8b627a4b87e7
```
Where `61eec2dc16ae8b627a4b87e7` will be a unique ID and you can track it back this to our [Messages API](/api/v1/email/messages).
For directions on how to collect this information, refer to your SMTP client documentation.
### Understanding error messages [#understanding-error-messages]
We use the same validation mechanisms for SMTP relay, which returns a string of concatenated validation errors with a `450` SMTP code, similar to this:
```
450 The given data was invalid. You must provide one of html, text or template_id.,You must provide one of html, text or template_id.,You must provide one of html, text or template_id.
```
You can refer to our [Email API](/api/v1/email) for the exact reasons behind errors that happen during validation.
For other possible SMTP codes, you can consult a source like [Wikipedia](https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes) or our [Knowledge base](https://www.mailersend.com/help/smtp-relay).
## Additional features [#additional-features]
### Custom tags [#custom-tags]
You can add a header to an SMTP message you send as follows:
```
X-MailerSend-Tags: "tag 1, tag 2, tag 3"
```
You can send a maximum of 5 tags.
This header must reside in the main MIME header node and not in additional MIME nodes like `text/plain` or `text/html`.
## Limitations [#limitations]
Most of the limitations that are in place for [Email API](/api/v1/email) endpoints are the same for SMTP relay.
These are the limitations that our users should be aware of:
* We only support `TLS` security via `587` port and do not have plans to support older/unsecure protocols for SMTP
* `FROM` email domain must be [verified](https://www.mailersend.com/help/how-to-verify-and-authenticate-a-sending-domain)
* A subject is required
* All custom headers, apart from the ones mentioned in [Additional features](#additional-features), will be dropped
* HTML source might be readjusted if [click or open tracking](https://www.mailersend.com/help/activity) is enabled
* Additional features like [advanced personalization](/api/v1/email/features#advanced-personalization) or [templates](https://www.mailersend.com/help/how-to-create-a-template) are only supported via our [Email API](/api/v1/email)
* We only support attachments of the file types as defined in [Email API](/api/v1/email#supported-file-types)
* There are [Rate limits](/general#rate-limits) applied to SMTP relay based on IP address and these tend to be lower than available through our API
* SMTP Relay has a single connection transaction limit set at 5. To send bulk emails use our [Bulk Email API](/api/v1/email#send-bulk-emails)
* [Daily request quota](https://developers.mailersend.com/general.html#daily-request-quota) applies to each individual message sent through our SMTP relay service. Be aware that the actual number of requests may vary depending on your SMTP client's email sending method.
* We do not support desktop email clients such as Apple Mail, Outlook, Thunderbird and similar applications.
If you encounter any other problems, or have a feature request, [let us know](https://www.mailersend.com/contact-us).
# Templates (/api/v1/email/templates)
Create and manage email templates via the MailerSend API.
## Get templates [#get-templates]
Retrieve the account templates using this `GET` request:
```http
GET https://api.mailersend.com/v1/templates
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `domain_id` | `string` | no | | |
| `page` | `int` | no | Min: `1` | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
// Get all templates of an account
$mailersend->template->getAll();
// Get all templates of a domain
$mailersend->template->getAll('domain_id');
// Get page 2 of templates with 20 records per page
$mailersend->template->getAll('domain_id', 2, 20);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.template.list({
domain_id: "domain_id"
})
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, TemplatesBuilder
ms = MailerSendClient()
request = (TemplatesBuilder()
.domain_id("domain-id")
.page(1)
.limit(25)
.build_templates_list_request())
response = ms.templates.list_templates(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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.ListTemplateOptions{
Page: 1,
Limit: 25,
}
_, _, err := ms.Template.List(ctx, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;
public void getTemplatesList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
TemplatesList list = ms.templates().getTemplates();
for (TemplateItem item : list.templates) {
System.out.println(item.id);
System.out.println(item.name);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_templates = Mailersend::Templates.new
ms_templates.list(domain_id: "aax455lll", page: 1, limit: 10)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "x8emy5o5world01w",
"name": "Signup email",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"tags": ["transactional", "welcome"],
"variables": {
"name": "",
"company": ""
},
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56"
},
{
"id": "x8emy5o5world01x",
"name": "Premium subscription",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"tags": [],
"variables": null,
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56"
},
{
"id": "x8emy5o5world01y",
"name": "Newsletter",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"tags": [],
"variables": null,
"created_at": "2020-06-10 10:09:56",
"updated_at": "2020-06-10 10:09:56"
}
],
"links": {
"first": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
"last": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https:\/\/www.mailersend.io\/api\/v1\/templates",
"per_page": 25,
"to": 3,
"total": 3
}
}
```
## Get a single template [#get-a-single-template]
Retrieve the information of a single template, its category, domain, and stats using this `GET` request:
```http
GET https://api.mailersend.com/v1/templates/{template_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `template_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->template->find('template_id');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.template.single("template_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, TemplatesBuilder
ms = MailerSendClient()
request = (TemplatesBuilder()
.template("template-id")
.build_template_get_request())
response = ms.templates.get_template(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
templateID := "template-id"
_, _, err := ms.Template.Get(ctx, templateID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;
public void getTemplate() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
Template template = ms.templates().getTemplate("template id");
System.out.println(template.id);
System.out.println(template.name);
System.out.println(template.imagePath);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_templates = Mailersend::Templates.new
ms_templates.single(template_id: "id124")
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
```json
{
"data": {
"id": "x8emy5o5world01w",
"name": "libero",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": {
"name": "",
"elements": [
{
"name": "",
"price": ""
}
],
"license_key": "",
"account_name": "",
"product_name": "",
"renew_button": "",
"expiration_date": ""
},
"tags": ["transactional"],
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T16:00:00.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "aut"
},
"domain": {
"id": "1jreeo",
"name": "domain.com",
"...",
"domain_settings": {
"..."
},
"totals": {
"hard_bounced": 25,
"soft_bounced": 40,
"sent": 231,
"delivered": 109
}
},
"template_stats": {
"total": 0,
"queued": 0,
"sent": 0,
"rejected": 0,
"delivered": 0,
"last_email_sent_at": null
}
}
}
```
#### Error [#error]
```http
Response Code: 404 Not Found
```
## Create a template [#create-a-template]
Create a new template using this `POST` request:
```http
POST https://api.mailersend.com/v1/templates
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TemplateParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$params = (new TemplateParams())
->setName('My Template')
->setHtml('Hello {{name}}
')
->setText('Hello {{name}}')
->setDomainId('domain_id')
->setCategories(['category_id'])
->setTags(['transactional', 'welcome']);
$mailersend->template->create($params);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, EmailTemplate } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const template = new EmailTemplate()
.setName("My Template")
.setHtml("Hello {{name}}
")
.setText("Hello {{name}}")
.setDomainId("domain_id")
.setCategories(["category_id"])
.setTags(["transactional", "welcome"]);
mailerSend.email.template.create(template)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, TemplatesBuilder
ms = MailerSendClient()
request = (TemplatesBuilder()
.name("My Template")
.html("Hello {{name}}
")
.text("Hello {{name}}")
.domain_id("domain-id")
.categories(["category-id"])
.tags(["transactional", "welcome"])
.build_template_create_request())
response = ms.templates.create_template(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
createOptions := &mailersend.CreateTemplateOptions{
Name: "My Template",
Html: "Hello {{name}}
",
Text: "Hello {{name}}",
DomainID: "domain-id",
Categories: []string{"category-id"},
Tags: []string{"transactional", "welcome"},
}
_, _, err := ms.Template.Create(ctx, createOptions)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
public void createTemplate() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
Template template = ms.templates().builder()
.name("My Template")
.html("Hello {{name}}
")
.text("Hello {{name}}")
.domainId("domain-id")
.addCategory("category-id")
.addTag("transactional")
.create();
System.out.println(template.id);
System.out.println(template.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_templates = Mailersend::Templates.new
ms_templates.create(
name: "My Template",
html: "Hello {{name}}
",
text: "Hello {{name}}",
domain_id: "domain_id",
categories: ["category_id"],
tags: ["transactional", "welcome"]
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc-2]
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| --------------- | --------- | -------- | ------------------------------------ | -------------------------------------------------------------------------- |
| `html` | `string` | yes | | The HTML body of the template. |
| `text` | `string` | yes | | Plain text version. Auto-generated from HTML if `auto_generate` is `true`. |
| `name` | `string` | no | Max: `50` | Defaults to `"Template"` if not provided. |
| `domain_id` | `string` | no | | Existing hashed domain ID. Must belong to the account. |
| `categories` | `array` | no | | Array of hashed category IDs. Each must belong to the account. |
| `tags` | `array` | no | Max: `5` items, each max `191` chars | Array of tag strings to attach to the template. |
| `auto_generate` | `boolean` | no | | If `true`, plain text is auto-generated from the HTML content. |
### Responses [#responses-2]
#### Valid [#valid-2]
```http
Response Code: 201 CREATED
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "x8emy5o5world01w",
"name": "My Template",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": null,
"tags": ["transactional", "welcome"],
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T15:38:51.000000Z",
"category": null,
"domain": null
}
}
```
#### Invalid [#invalid]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Update a template [#update-a-template]
Update an existing template using this `PUT` request. Only templates created via API (`origin=api`) can be updated — templates created in the MailerSend app return `404`.
```http
PUT https://api.mailersend.com/v1/templates/{template_id}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TemplateParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$params = (new TemplateParams())
->setName('Updated Template Name')
->setHtml('Hello {{name}}, your updated content here.
')
->setText('Hello {{name}}, your updated content here.')
->setTags(['transactional']);
$mailersend->template->update('template_id', $params);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, EmailTemplate } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const template = new EmailTemplate()
.setName("Updated Template Name")
.setHtml("Hello {{name}}, your updated content here.
")
.setText("Hello {{name}}, your updated content here.")
.setTags(["transactional"]);
mailerSend.email.template.update("template_id", template)
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, TemplatesBuilder
ms = MailerSendClient()
request = (TemplatesBuilder()
.template("template-id")
.name("Updated Template Name")
.html("Hello {{name}}, your updated content here.
")
.text("Hello {{name}}, your updated content here.")
.tags(["transactional"])
.build_template_update_request())
response = ms.templates.update_template(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
templateID := "template-id"
updateOptions := &mailersend.UpdateTemplateOptions{
Name: "Updated Template Name",
Html: "Hello {{name}}, your updated content here.
",
Text: "Hello {{name}}, your updated content here.",
Tags: []string{"transactional"},
}
_, _, err := ms.Template.Update(ctx, templateID, updateOptions)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
public void updateTemplate() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
Template template = ms.templates().builder()
.name("Updated Template Name")
.html("Hello {{name}}, your updated content here.
")
.text("Hello {{name}}, your updated content here.")
.addTag("transactional")
.update("template-id");
System.out.println(template.id);
System.out.println(template.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_templates = Mailersend::Templates.new
ms_templates.update(
template_id: "template_id",
name: "Updated Template Name",
html: "Hello {{name}}, your updated content here.
",
text: "Hello {{name}}, your updated content here.",
tags: ["transactional"]
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc-3]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------- |
| `template_id` | `string` | yes | | |
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| --------------- | --------- | -------- | ------------------------------------ | --------------------------------------------------------------------------- |
| `html` | `string` | no | | The HTML body of the template. |
| `text` | `string` | no | | Plain text version. Auto-generated from HTML if `auto_generate` is `true`. |
| `name` | `string` | no | Max: `50` | |
| `domain_id` | `string` | no | | Existing hashed domain ID. Must belong to the account. |
| `categories` | `array` | no | | Array of hashed category IDs. Pass an empty array to remove all categories. |
| `tags` | `array` | no | Max: `5` items, each max `191` chars | Array of tag strings to attach to the template. |
| `auto_generate` | `boolean` | no | | If `true`, plain text is auto-generated from the HTML content. |
### Responses [#responses-3]
#### Valid [#valid-3]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "x8emy5o5world01w",
"name": "Updated Template Name",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": null,
"tags": ["transactional"],
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T16:00:00.000000Z",
"category": null,
"domain": null
}
}
```
#### Invalid [#invalid-1]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
## Delete a template [#delete-a-template]
Delete a template with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/templates/{template_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-4]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | ------ | -------- | ----------- | ------- |
| `template_id` | string | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->template->delete('template_id');
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend} from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.template.delete("template_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, TemplatesBuilder
ms = MailerSendClient()
request = (TemplatesBuilder()
.template("template-id")
.build_delete_request())
response = ms.templates.delete_template(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
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()
templateID := "template-id"
_, err := ms.Template.Delete(ctx, templateID)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;
public void deleteTemplate() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
MailerSendResponse response = ms.templates().deleteTemplate("template id");
System.out.println(response.responseStatusCode);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_templates = Mailersend::Templates.new
ms_templates.delete(template_id: "id124")
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-4]
#### Valid [#valid-4]
```http
Response Code: 200 OK
Response Body: [EMPTY]
```
#### Error [#error-2]
```http
Response Code: 404 Not Found
```
## Email Survey Templates [#email-survey-templates]
Using our drag-and-drop email [builder](https://app.mailersend.com/templates/gallery/dd), you may create email templates with a survey block to ask questions and reviews to your recipients. When your recipient receives an email with a survey, they can preview the email and answer your survey questions. Then the responses are sent to your webhook if available.\
\
When a recipient answers all available survey questions the responses are immediately sent to your webhook(if available). However, when a recipient doesn't completely answer all available questions, after an idle time of `30` minutes, the responses would be sent.\
\
Rules and steps for sending an email with a survey include:
* You cannot use the following variables `{{url}}`, `{{survey}}`, `{{survey_last_question}}`, as they are reserved.
* You must enable `content_tracking` on your domain by selecting your domain and enabling the setting under tracking details. Content tracking is a feature available on Starter plans and above.
* Add a webhook with the `activity.survey_submitted` event to receive the survey answers.
* You can also include the `activity.survey_opened` event in your webhook to know when a recipient has opened an email containing a survey at least once.
### Payloads [#payloads]
#### Example of `activity.survey_submitted` data sent to your webhook: [#example-of-activitysurvey_submitted-data-sent-to-your-webhook]
```json
{
"type": "activity.survey_submitted",
"created_at": "2025-08-06T00:20:36.589903Z",
"data": {
"id": "68929fd47f916891ef12eba9",
"domain_id": "7nxe3yjmeq28vp0k",
"message_id": "68929fd402fd7079a02cf858",
"email_id": "68929fd47f916891ef12eba9",
"type": "survey_submitted",
"subject": "Test email",
"from": "test@domain.com",
"tags": [
"test2",
"test3"
],
"meta": {
"surveys": [
{
"question_id": 1,
"survey_id": 1,
"answer": "test",
"is_last_question": true
}
]
}
}
}
```