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": 1200,
"queued": 0,
"sent": 4,
"rejected": 16,
"delivered": 1180,
"delivery_rate": "98",
"opened": 590,
"open_rate": "50",
"clicked": 118,
"click_rate": "10",
"unsubscribed": 2,
"unsubscribe_rate": "0",
"complained": 0,
"complain_rate": "0",
"last_email_sent_at": "2026-10-13T09:30:00.000000Z"
}
}
}
```
#### Error [#error]
```http
Response Code: 404 Not Found
```
### Template stats [#template-stats]
`template_stats` holds the sending stats for the template.
Template stats are all-time totals for the template and can't be filtered by date. They aren't real-time, so a recent send may not show yet. For stats over a date range, tag your emails and use [Activity data by date](/api/v1/email/analytics#activity-data-by-date) filtered by tag.
| Field | Type | Details |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `total` | `integer` | All emails sent with this template, in any status. |
| `queued` | `integer` | Emails waiting to be sent. |
| `sent` | `integer` | Emails sent and waiting for a delivery result. |
| `rejected` | `integer` | Emails that could not be delivered. |
| `delivered` | `integer` | Emails delivered. |
| `delivery_rate` | `string\|integer` | `delivered` as a whole-number percentage of `total`, e.g. `"98"`. `0` when `total` is 0. |
| `opened` | `integer` | Delivered emails opened at least once. Each email counts once. |
| `open_rate` | `string\|integer` | `opened` as a whole-number percentage of `delivered`, e.g. `"50"`. `0` when `delivered` is 0. |
| `clicked` | `integer` | Delivered emails clicked at least once. Each email counts once. |
| `click_rate` | `string\|integer` | `clicked` as a whole-number percentage of `delivered`. `0` when `delivered` is 0. |
| `unsubscribed` | `integer` | Emails whose recipient unsubscribed. |
| `unsubscribe_rate` | `string\|integer` | `unsubscribed` as a whole-number percentage of `delivered`. `0` when `delivered` is 0. |
| `complained` | `integer` | Emails the recipient marked as spam. |
| `complain_rate` | `string\|integer` | `complained` as a whole-number percentage of `delivered`. `0` when `delivered` is 0. |
| `last_email_sent_at` | `string\|null` | When an email with this template was last sent. `null` if none has been sent. |
## 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
}
]
}
}
}
```
# Activity (/api/v1/sms/activity)
Get information about your SMS activity, including your sent SMS messages, and whether they were received by the recipient.
## Get a list of activities [#get-a-list-of-activities]
With this endpoint, you can retrieve every single data point of the activity that happened for a specific phone number.
Get a list of activities with the following `GET` request:
```http
GET https://api.mailersend.com/v1/sms-activity
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details | |
| --------------- | ---------- | -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | - |
| `sms_number_id` | `string` | no | | | |
| `date_from` | `int` | no | Timestamp is assumed to be `UTC`. Must be lower than `date_to` | Format: `1443651141` | |
| `date_to` | `int` | no | Timestamp is assumed to be `UTC`. Must be higher than `date_from` | Format: `1443651141` | |
| `status[]` | `string[]` | no | Possible types: `processed`,`queued`,`sent`,`delivered`, `failed` | | |
| `page` | `int` | no | Min: `1`, Max: `1000` | To reach older activity beyond the last page, narrow `date_from` and `date_to` | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` | |
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsActivityParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsActivityParams = (new SmsActivityParams())
->setSmsNumberId('sms_number_id')
->setDateFrom(1623073576)
->setDateTo(1623074976)
->setStatus(['queued', 'delivered'])
->setPage(3)
->setLimit(15);
$smsActivity = $mailersend->smsActivity->getAll($smsActivityParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, SmsActivityStatusType } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.sms.activity.list({
sms_number_id: "number_id",
status: [SmsActivityStatusType.SENT, SmsActivityStatusType.DELIVERED],
limit: 10,
page: 1
})
.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, SmsActivityBuilder
from datetime import datetime, timedelta
ms = MailerSendClient()
# Get activities from last 7 days
date_from = int((datetime.now() - timedelta(days=7)).timestamp())
date_to = int(datetime.now().timestamp())
request = (SmsActivityBuilder()
.sms_number_id("sms-number-id")
.date_from(date_from)
.date_to(date_to)
.status(["sent", "delivered", "failed"])
.page(1)
.limit(25)
.build_list_request())
response = ms.sms_activity.list(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.SmsActivityOptions{}
_, _, err := ms.SmsActivityService.List(context.TODO(), 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.mailsend.sdk.sms.activities.SmsActivityList;
import com.mailsend.sdk.sms.activities.SmsActivity;
public void getActivities() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsActivityList list = ms.sms().activities().getActivities();
for (SmsActivity activity : lists.smsActivities) {
System.out.println(activity.id);
System.out.println(activity.content);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_activity = Mailersend::SMSActivity.new
# Add parameters
ms_sms_activity.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": [
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:46.627000Z",
"content": "Lorem Ipsum is simply dummy text",
"status": "delivered",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:42.508000Z",
"content": "Lorem Ipsum is simply dummy text",
"status": "processed",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:42.579000Z",
"content": "Lorem Ipsum is simply dummy text",
"status": "queued",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:43.624000Z",
"content": "Lorem Ipsum is simply dummy text",
"status": "sent",
"sms_message_id": "62134a2d7de3253bf10d6642"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/sms-activity?page=1",
"last": null,
"prev": null,
"next": "https:\/\/api.mailersend.com\/v1\/sms-activity?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/sms-activity",
"per_page": 25,
"to": 1
}
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
## Get activity of a single message [#get-activity-of-a-single-message]
With this endpoint, you can get every single activity data point that happened to a specific SMS message.
Get a list of activities for the SMS message specified with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-messages/{sms_message_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ---------------- | ------ | -------- | ----------- | ------- |
| `sms_message_id` | string | yes | | |
```javascript
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.sms.activity.single("sms_message_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, SmsActivityBuilder
ms = MailerSendClient()
request = (SmsActivityBuilder()
.sms_message_id("sms-message-id")
.build_get_request())
response = ms.sms_activity.get(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()
_, _, err := ms.SmsActivityService.Get(context.TODO(), "message-id")
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.mailsend.sdk.sms.activities.SmsActivity;
public void getActivity() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsActivity activity = ms.sms().activities().getMessageActivity("message id");
System.out.println(activity.id);
System.out.println(activity.content);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
### Responses [#responses-1]
#### Valid [#valid-1]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "62134a2d7de3253bf10d6642",
"from": "+18332647501",
"to": [
"+16203221059",
"+18044064234"
],
"text": "Lorem Ipsum is simply dummy text",
"paused": false,
"created_at": "2022-02-21T08:15:41.339000Z",
"sms": [
{
"id": "62134a2e4709ec689f72ea62",
"from": "+18332647501",
"to": "+16203221059",
"text": "Lorem Ipsum is simply dummy text",
"status": "delivered",
"segment_count": 1,
"error_type": null,
"error_description": null
}
],
"sms_activity": [
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:46.627000Z",
"status": "delivered",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:42.508000Z",
"status": "processed",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:42.579000Z",
"status": "queued",
"sms_message_id": "62134a2d7de3253bf10d6642"
},
{
"from": "+18332647501",
"to": "+16203221059",
"created_at": "2022-02-21T08:15:43.624000Z",
"status": "sent",
"sms_message_id": "62134a2d7de3253bf10d6642"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
# Inbound routing (/api/v1/sms/inbounds)
## Get a list of SMS inbound routes [#get-a-list-of-sms-inbound-routes]
If you want to retrieve information about multiple SMS inbound routes, use this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-inbounds
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | --------- | -------- | --------------------- | ------------- |
| `sms_number_id` | `string` | no | | |
| `enabled` | `boolean` | no | | |
| `page` | `int` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsInbound->getAll($smsNumberId = 'sms_number_id', $enabled = true, $page = 3, $limit = 15);
```
[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.sms.inbound.list({
enabled: 1,
sms_number_id: "sms_number_id",
limit: 10,
page: 1,
})
.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, SmsInboundsBuilder
ms = MailerSendClient()
request = (SmsInboundsBuilder()
.sms_number_id("sms-number-id")
.enabled(True)
.build_list_request())
response = ms.sms_inbounds.list_sms_inbounds(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.ListSmsInboundOptions{
SmsNumberId: "sms-number-id",
}
_, _, err := ms.SmsInbound.List(ctx, listOptions)
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.sms.inboundroutes.SmsInboundRoute;
import com.mailersend.sdk.sms.inboundroutes.SmsInboundRouteList;
public void getSmsInboundRoutes() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsInboundRouteList routes = ms.sms().inboundRoutes().getSmsInboundRoutes();
for (SmsInboundRoute route : routes.routes) {
System.out.println(route.id);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
ms_sms_inbounds.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": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"filter": {
"value": "START",
"comparer": "equal"
},
"forward_url": "https://yourapp.com/hook",
"enabled": true,
"secret": "jYhafGtTiZgw0qWxlkUA7cbqTG3Zfh2j",
"created_at": "2022-01-01T12:00:00.000000Z"
}
]
}
```
#### Error [#error]
```http
Response Code: 404 Not Found
```
## Get a single SMS inbound route [#get-a-single-sms-inbound-route]
If you want to retrieve a single SMS inbound route, use this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-inbounds/{sms_inbound_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_inbound_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsInbound->find('sms_inbound_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.sms.inbound.single("sms_inbound_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, SmsInboundsBuilder
ms = MailerSendClient()
request = (SmsInboundsBuilder()
.sms_inbound_id("inbound-id")
.build_get_request())
response = ms.sms_inbounds.get_sms_inbound(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()
_, _, err := ms.SmsInbound.Get(ctx, "sms-inbound-id")
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.sms.inboundroutes.SmsInboundRoute;
public void getSmsInboundRoute() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsInboundRoute route = ms.sms().inboundRoutes().getSmsInboundRoute("route id");
System.out.println(route.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.get_sms_inbound_route(sms_inbound_id: 'your-sms-inbound-id')
```
[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": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"filter": {
"value": "START",
"comparer": "equal"
},
"forward_url": "https://yourapp.com/hook",
"enabled": true,
"secret": "jYhafGtTiZgw0qWxlkUA7cbqTG3Zfh2j",
"created_at": "2022-01-13T12:00:00.000000Z",
"sms_number": {
"id": "7z3m5jgrogdpyo6n",
"telephone_number": "+19199876543",
"paused": false,
"created_at": "2022-01-13T12:00:00.000000Z"
}
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
## Add an SMS inbound route [#add-an-sms-inbound-route]
If you want to add a new SMS inbound route to a domain, use this `POST` request:
```http
POST https://api.mailersend.com/v1/sms-inbounds
```
### Request body \[!toc] [#request-body-toc]
```json
{
"sms_number_id": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"forward_url": "https://yourapp.com/hook",
"filter": {
"comparer": "equal",
"value": "START"
},
"enabled": true
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsInbound;
use MailerSend\Helpers\Builder\SmsInboundFilter;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsInboundParams = (new SmsInbound())
->setSmsNumberId('sms_number_id')
->setName('Name')
->setForwardUrl('https://mailersend.com/inbound_webhook')
->setFilter(new SmsInboundFilter($comparer = 'starts-with', $value = 'Stop'))
->setEnabled(true);
$smsRecipients = $mailersend->smsInbound->create($smsInboundParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, SmsInbound } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const smsInbound = new SmsInbound()
.setSmsNumberId("sms_number_id")
.setEnabled(true)
.setName("Inbound Name")
.setForwardUrl("yourapp.com/hook")
.setFilter({
comparer: "equal",
value: "START"
});
mailerSend.sms.inbound.create(smsInbound)
.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, SmsInboundsBuilder
from mailersend.models.sms_inbounds import FilterComparer
ms = MailerSendClient()
request = (SmsInboundsBuilder()
.sms_number_id("sms-number-id")
.name("Support Route")
.forward_url("https://api.example.com/sms/support")
.filter(FilterComparer.STARTS_WITH, "SUPPORT")
.enabled(True)
.build_create_request())
response = ms.sms_inbounds.create_sms_inbound(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.settings =
{
'forward_url' => 'https://your-forward-url',
'name' => 'name',
'events' => ['sms.sent', 'sms.delivered'],
'sms_number_id' => 'your-sms-number-id'
}
puts ms_sms_inbounds.add_sms_inbound_route
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.sms.inboundroutes.SmsInboundRoute;
public void addSmsInboundRoute() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsInboundRoute route = ms.sms().inboundRoutes().builder()
.smsNumberId("sms number id")
.name("Test inbound route")
.enabled(false)
.forwardUrl("https://example.com")
.filter("equal", "START")
.addSmsInboundRoute();
System.out.println(route.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.settings =
{
'forward_url' => 'https://your-forward-url',
'name' => 'name',
'events' => ['sms.sent', 'sms.delivered'],
'sms_number_id' => 'your-sms-number-id'
}
puts ms_sms_inbounds.add_sms_inbound_route
```
[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 |
| ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `sms_number_id` | `string` | Yes | | |
| `name` | `string` | Yes | `Max` 191 characters. | |
| `forward_url` | `string` | Yes | | |
| `filter` | `object` | No | | |
| `filter.comparer` | `string` | Yes\* | Must be one of the comparers: `equal`, `not-equal`, `contains`, `not-contains`, `starts-with`, `ends-with`, `not-starts-with`, `not-ends-with`. | |
| `filter.value` | `string` | Yes\* | Min: `1`, `Max` 255 characters. | |
| `enabled` | `boolean` | No | | |
###### \* Required when `filter` object is provided. [#-required-when-filter-object-is-provided]
### Responses [#responses-2]
| Response Key | Type | Details |
| ------------ | ------ | --------------------------- |
| data | object | SMS Inbound object created. |
#### Valid [#valid-2]
```http
Response Code: 201 CREATED
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"filter": {
"value": "START",
"comparer": "equal"
},
"forward_url": "https://yourapp.com/hook",
"enabled": true,
"secret": "jYhafGtTiZgw0qWxlkUA7cbqTG3Zfh2j",
"created_at": "2022-01-01T12:00:00.000000Z"
}
}
```
#### Invalid [#invalid]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Update an inbound route [#update-an-inbound-route]
If you want to update the information of an existing inbound route, use this `PUT` request:
```http
PUT https://api.mailersend.com/v1/sms-inbounds/{sms_inbound_id}
```
### Request body \[!toc] [#request-body-toc-1]
```json
{
"sms_number_id": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"forward_url": "https://yourapp.com/hook",
"filter": {
"comparer": "equal",
"value": "START"
},
"enabled": true
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsInbound;
use MailerSend\Helpers\Builder\SmsInboundFilter;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsInboundParams = (new SmsInbound())
->setSmsNumberId('sms_number_id')
->setName('Name')
->setForwardUrl('https://mailersend.com/inbound_webhook')
->setFilter(new SmsInboundFilter($comparer = 'starts-with', $value = 'Stop'))
->setEnabled(true);
$smsRecipients = $mailersend->smsInbound->update('sms_inbound_id', $smsInboundParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, SmsInbound } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const smsInbound = new SmsInbound()
.setSmsNumberId("sms_number_id")
.setEnabled(true)
.setName("Inbound Name Update")
.setForwardUrl("yourapp.com/hook")
.setFilter({
comparer: "equal",
value: "START"
});
mailerSend.sms.inbound.update("sms_inbound_id", {...smsInbound})
.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, SmsInboundsBuilder
from mailersend.models.sms_inbounds import FilterComparer
ms = MailerSendClient()
request = (SmsInboundsBuilder()
.sms_number_id("inbound-id")
.name("Updated Support Route")
.forward_url("https://api.example.com/sms/new-support")
.filter(FilterComparer.CONTAINS, "HELP")
.enabled(False)
.build_update_request())
response = ms.sms_inbounds.update_sms_inbound(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.settings =
{
'forward_url' => 'https://your-forward-url',
'name' => 'name',
'events' => ['sms.sent', 'sms.delivered'],
'sms_number_id' => 'your-sms-number-id'
}
puts ms_sms_inbounds.update_sms_inbound_route(sms_inbound_id: 'your-sms-inbound-id')
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.sms.inboundroutes.SmsInboundRoute;
public void updateSmsInboundRoute() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsInboundRoute route = ms.sms().inboundRoutes().builder()
.smsNumberId("sms number id")
.name("Test inbound route updated")
.enabled(false)
.forwardUrl("https://example.com")
.filter("equal", "START")
.updateSmsInboundRoute("route id");
System.out.println(route.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.settings =
{
'forward_url' => 'https://your-forward-url',
'name' => 'name',
'events' => ['sms.sent', 'sms.delivered'],
'sms_number_id' => 'your-sms-number-id'
}
puts ms_sms_inbounds.update_sms_inbound_route(sms_inbound_id: 'your-sms-inbound-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Request Parameters \[!toc] [#request-parameters-toc-3]
| URL parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_inbound_id` | `string` | yes | | |
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `sms_number_id` | `string` | No | | |
| `name` | `string` | No | `Max` 191 characters. | |
| `forward_url` | `string` | No | | |
| `filter` | `object` | No | | |
| `filter.comparer` | `string` | Yes\* | Must be one of the comparers: `equal`, `not-equal`, `contains`, `not-contains`, `starts-with`, `ends-with`, `not-starts-with`, `not-ends-with`. | |
| `filter.value` | `string` | Yes\* | Min: `1`, `Max` 255 characters. | |
| `enabled` | `boolean` | No | | |
###### \* Required when `filter` object is provided. [#-required-when-filter-object-is-provided-1]
### Responses [#responses-3]
| Response Key | Type | Details |
| ------------ | ------ | --------------------------- |
| data | object | SMS Inbound object created. |
#### Valid [#valid-3]
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "7z3m5jgrogdpyo6n",
"name": "Inbound",
"filter": {
"value": "START",
"comparer": "equal"
},
"forward_url": "https://yourapp.com/hook",
"enabled": true,
"secret": "jYhafGtTiZgw0qWxlkUA7cbqTG3Zfh2j",
"created_at": "2022-01-01T12:00:00.000000Z"
}
}
```
#### Invalid [#invalid-1]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Delete an SMS inbound route [#delete-an-sms-inbound-route]
If you want to delete an SMS inbound route, use this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/sms-inbounds/{sms_inbound_id}
```
### Request parameters \[!toc] [#request-parameters-toc-4]
| URL parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_inbound_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsInbound->delete('sms_inbound_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.sms.inbound.delete("sms_inbound_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, SmsInboundsBuilder
ms = MailerSendClient()
request = (SmsInboundsBuilder()
.sms_inbound_id("inbound-id")
.build_delete_request())
response = ms.sms_inbounds.delete_sms_inbound(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()
_, err := ms.SmsInbound.Delete(ctx, "sms-inbound-id")
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.sms.inboundroutes.SmsInboundRoute;
public void deleteSmsInboundRoute() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
boolean result = ms.sms().inboundRoutes().deleteSmsInboundRoute("route id");
System.out.println(result);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Inbounds class
ms_sms_inbounds = Mailersend::SMSInbounds.new
# Add parameters
ms_sms_inbounds.delete_sms_inbound_route(sms_inbound_id: 'your-sms-inbound-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-4]
#### Valid [#valid-4]
```http
Response Code: 200 OK
```
#### Error [#error-2]
```http
Response Code: 404 Not Found
```
# Sending an SMS (/api/v1/sms)
This endpoint allows you to start sending SMSs through MailerSend SMS API.
## Send an SMS [#send-an-sms]
This endpoint allows you to send an asynchronous SMS. It returns the status of the SMS sent with a `X-SMS-Message-Id` that can be used to continuously query for the status using the SMS API.
Send an SMS using this `POST` request:
```http
POST https://api.mailersend.com/v1/sms
```
#### Request Body \[!toc] [#request-body-toc]
```json
{
"from": "+19191234567",
"to": [
"+19191234567",
"+19199876543"
],
"text": "Hey {{name}}! This is just a friendly hello :D",
"personalization": [
{
"phone_number": "+19191234567",
"data": {
"name": "Dummy"
}
},
{
"phone_number": "+19199876543",
"data": {
"name": "Not Dummy"
}
}
]
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsParams = (new SmsParams())
->setFrom('+12065550101')
->setTo(['+12065550102'])
->addRecipient('+12065550103')
->setText('Text');
$sms = $mailersend->sms->send($smsParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
"use strict";
require('dotenv').config()
const MailerSend = require("../../src/MailerSend");
const SmsParams = require("../../src/SmsParams");
const mailersend = new MailerSend({
api_key: process.env.API_KEY,
});
const recipients = [
"+18332647501"
];
const smsParams = new SmsParams()
.setFrom("+18332647501")
.setRecipients(recipients)
.setText("This is the text content");
mailersend.sendSms(smsParams);
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, SmsSendingBuilder
ms = MailerSendClient()
# Simple SMS
request = (SmsSendingBuilder()
.from_number("sms-number")
.to(["+1234567890", "+1234567891"])
.text("Hello from MailerSend SMS!")
.build())
response = ms.sms_sending.send(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
package main
import (
"context"
"fmt"
"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()
message := ms.Sms.NewMessage()
message.SetFrom("your-number")
message.SetTo([]string{"client-number"})
message.SetText("This is the message content {{ var }}")
personalization := []mailersend.SmsPersonalization{
{
PhoneNumber: "client-number",
Data: map[string]interface{}{
"var": "foo",
},
},
}
message.SetPersonalization(personalization)
res, _ := ms.Sms.Send(context.TODO(), message)
fmt.Printf(res.Header.Get("X-SMS-Message-Id"))
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
public void sendSms() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
String messageId = ms.sms().builder().from("from phone number")
.addRecipient("to phone number")
.text("test sms {{name}}")
.addPersonalization("to phone number", "name", "name personalization")
.send();
System.out.println(messageId);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS class
ms_sms = Mailersend::SMS.new
# Add parameters
ms_sms.add_from('your-number')
ms_sms.add_to('client-number')
ms_sms.add_text('This is the message content')
personalization = {
phone_number: 'client-number',
data: {
test: 'Test Value'
}
}
ms_sms.add_personalization(personalization)
# Send the SMS
ms_sms.send
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc]
*JSON parameters are provided in dot notation*
| JSON parameter | Type | Required | Limitations | Details |
| -------------------------------- | ---------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from` | `string` | yes | | Number belonging to your account in E164 format |
| `to` | `string[]` | yes | `min:1`,`max:50` | |
| `to.*` | `string` | yes | `US`, `CA` | The phone number(s) the message should be sent to in E164 format |
| `text` | `string` | yes | `Max lenght:2048` | The contents of the text message. Must be 2048 characters or less. Curly braces (`{` and `}`) are not allowed.
If the body of your message is more than 160 GSM-7 characters or 70 UCS-2 characters, MailerSend will split the message into a segmented SMS and add a special header ([User Data Header](https://en.wikipedia.org/wiki/User_Data_Header)). Please note you are billed by segment.
The User Data Header (UDH) takes up 6 bytes and instructs the receiving device how to reassemble the segments so that your whole message will be shown as one SMS on the receiving handset. The maximum number of characters per concatenated (long) message is slightly reduced due to the inclusion of concatenation headers (UDH).
You can see the difference between GSM-7 and UCS-2 and how they're segmented [here](https://chadselph.github.io/smssplit/). |
| `personalization` | `object[]` | no | | Allows using personalization in `{{ var }}` syntax. Can be used in the `text` fields. Read more about [advanced personalization](/features#advanced-personalization). |
| `personalization.*.phone_number` | `string` | yes | | Phone number that personalization will be applied to. |
| `personalization.*.data` | `object[]` | yes | | Object with `key: value` pairs. Values will be added to your template using `{{ key }}` syntax. |
### Responses [#responses]
#### Sending queued [#sending-queued]
```http
Response Code: 202 Accepted
Response Headers:
Content-Type: text/plain; charset=utf-8
X-SMS-Message-Id: 5e42957d51f1d94a1070a733
Response Body: [EMPTY]
```
#### Sending paused [#sending-paused]
```http
Response Code: 202 Accepted
Response Headers:
Content-Type: text/plain; charset=utf-8
X-SMS-Message-Id: 5e42957d51f1d94a1070a733
X-SMS-Send-Paused: true
Response Body: [EMPTY]
```
#### Validation error [#validation-error]
```http
Response Code: 422 Unprocessable Entity
Response Headers:
content-type: application/json
```
```json
{
"message": "The given data was invalid.",
"errors": {
"from": [
"The from field contains an invalid number."
]
}
}
```
*See - [Validations errors](/../../general#validation-errors)*
# Messages (/api/v1/sms/messages)
SMS Messages are resources that are created from a single SMS API request.
## Get a list of SMS messages [#get-a-list-of-sms-messages]
Get a list of SMS messages information with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-messages
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | ----- | -------- | --------------------- | ------------- |
| `page` | `int` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsMessages = $mailersend->smsMessage->getAll($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.sms.message.list({
limit: 10,
page: 1
})
.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, SmsMessagesBuilder
ms = MailerSendClient()
request = (SmsMessagesBuilder()
.page(1)
.limit(25)
.build_sms_messages_list())
response = ms.sms_messages.list_sms_messages(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.ListSmsMessageOptions{
Limit: 10,
}
_, _, err := ms.SmsMessage.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.mailsend.sdk.sms.messages.SmsMessageList;
import com.mailsend.sdk.sms.messages.SmsMessage;
public void getSmsMessages() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsMessageList list = ms.sms().messages().getMessages();
for (SmsMessage message : list.messages) {
System.out.println(message.id);
System.out.println(message.text);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Messages class
ms_sms_messages = Mailersend::SMSMessages.new
# Add parameters
ms_sms_messages.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": "6203a0cc00033b7d341d0f52",
"from": "+19191234567",
"to": [
"+19199876543"
],
"text": "Hello world",
"paused": false,
"created_at": "2022-01-01T12:00:00.000000Z"
},
...
]
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
## Get an SMS message [#get-an-sms-message]
Get a single SMS message.
```http
GET https://api.mailersend.com/v1/sms-messages/{sms_message_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_message_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsMessage = $mailersend->smsMessage->find('sms_message_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.sms.message.single("sms_message_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, SmsMessagesBuilder
ms = MailerSendClient()
request = (SmsMessagesBuilder()
.sms_message_id("message-id")
.build_sms_message_get())
response = ms.sms_messages.get_sms_message(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()
_, _, err := ms.SmsMessage.Get(ctx, "sms-message-id")
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.mailsend.sdk.sms.messages.SmsMessage;
public void getSmsMessage() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsMessage message = ms.sms().messages().getMessage("message id");
System.out.println(message.id);
System.out.println(message.text);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Messages class
ms_sms_messages = Mailersend::SMSMessages.new
# Add parameters
ms_sms_messages.get_single_route(sms_message_id: 'your-sms-message-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
| Response key | Type | Details |
| ------------ | ---------- | ---------------------------------------------------------------- |
| `data.sms.*` | `object[]` | Will include `sms` data, if it has been created in the database. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "01h909rj94ybjnvpke60w866n6",
"from": "+18332552485",
"to": [
"+16062149989"
],
"text": "Hey Jane! Your verification code is 1234567890.",
"paused": false,
"created_at": "2023-08-29T09:24:58.000000Z",
"sms": [
{
"id": "01h909rjj42mjxcpkxv6asq1jn",
"from": "+18332552485",
"to": "+16062149989",
"text": "Hey Jane! Your verification code is 1234567890.",
"compiled_text": "Hey Jane! Your verification code is 1234567890.",
"status": "sent",
"segment_count": 1,
"error_type": null,
"error_description": null,
"created_at": "2023-08-29T09:24:59.000000Z"
}
],
"sms_activity": [
{
"from": "+18332552485",
"to": "+16062149989",
"created_at": "2023-08-29T09:24:59.000000Z",
"status": "processed",
"sms_message_id": "01h909rj94ybjnvpke60w866n6"
},
{
"from": "+18332552485",
"to": "+16062149989",
"created_at": "2023-08-29T09:24:59.000000Z",
"status": "queued",
"sms_message_id": "01h909rj94ybjnvpke60w866n6"
},
{
"from": "+18332552485",
"to": "+16062149989",
"created_at": "2023-08-29T09:24:59.000000Z",
"status": "sent",
"sms_message_id": "01h909rj94ybjnvpke60w866n6"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
# Phone numbers (/api/v1/sms/numbers)
Get information about SMS phone numbers.
## Get a list of SMS phone numbers [#get-a-list-of-sms-phone-numbers]
Get a list of SMS phone numbers information with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-numbers
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | ----- | -------- | --------------------- | ------------- |
| `paused` | bool | no | | |
| `page` | `int` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$sms = $mailersend->smsNumber->getAll($page = 1, $limit = 10, $paused = true);
```
[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.sms.number.single("sms_number_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, SmsNumbersBuilder
ms = MailerSendClient()
request = (SmsNumbersBuilder()
.paused(False)
.page(1)
.limit(25)
.build_list_request())
response = ms.sms_numbers.list(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.SmsNumberOptions{}
_, _, err := ms.SmsNumber.List(context.TODO(), 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.sms.phonenumbers.PhoneNumber;
import com.mailersend.sdk.sms.phonenumbers.PhoneNumberList;
public void getSmsPhoneNumbers() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
PhoneNumberList numbers = ms.sms().phoneNumbers().getPhoneNumbers();
for (PhoneNumber number : numbers.phoneNumbers) {
System.out.println(number.id);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_number = Mailersend::SMSNumber.new
# Add parameters
ms_sms_number.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": "7z3m5jgrogdpyo6n",
"telephone_number": "+1234567890",
"paused": false,
"created_at": "2022-01-01T12:00:00.000000Z"
},
...
]
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
## Get an SMS phone number [#get-an-sms-phone-number]
Get information about a specific SMS phone number with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-numbers/{sms_number_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| --------------- | ------ | -------- | ----------- | ------- |
| `sms_number_id` | string | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$sms = $mailersend->smsNumber->find('sms_number_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.sms.number.single("sms_number_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, SmsNumbersBuilder
ms = MailerSendClient()
request = (SmsNumbersBuilder()
.sms_number_id("sms-number-id")
.build_get_request())
response = ms.sms_numbers.get(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()
_, _, err := ms.SmsNumber.Get(context.TODO(), "number-id")
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.sms.phonenumbers.PhoneNumber;
public void getSmsPhoneNumber() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
PhoneNumber number = ms.sms().phoneNumbers().getPhoneNumber("phone number id");
System.out.println(number.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_number = Mailersend::SMSNumber.new
# Add parameters
ms_sms_number.get(sms_number_id: 'your-sms-number-id')
```
[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": "7z3m5jgrogdpyo6n",
"telephone_number": "+1234567890",
"paused": false,
"created_at": "2022-01-01T12:00:00.000000Z"
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
## Update a single SMS phone number [#update-a-single-sms-phone-number]
Update a specific SMS phone number with this `PUT` request:
```http
PUT https://api.mailersend.com/v1/sms-numbers/{sms_number_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
| URL parameter | Type | Required | Limitations | Details |
| --------------- | ------ | -------- | ----------- | ------- |
| `sms_number_id` | string | yes | | |
| Query parameter | Type | Required | Limitations | Details |
| --------------- | ------ | -------- | ----------- | ------- |
| `paused` | `bool` | no | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$sms = $mailersend->smsNumber->update('sms_number_id', $paused = true);
```
[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.sms.number.update("sms_number_id", true)
.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, SmsNumbersBuilder
ms = MailerSendClient()
request = (SmsNumbersBuilder()
.sms_number_id("sms-number-id")
.paused(True)
.build_update_request())
response = ms.sms_numbers.update(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.SmsNumberSettingOptions{
Id: "number-id",
Paused: mailersend.Bool(false),
}
_, _, err := ms.SmsNumber.Update(context.TODO(), 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.sms.phonenumbers.PhoneNumber;
public void updateSmsPhoneNumber() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
boolean pausePhoneNumber = false;
PhoneNumber number = ms.sms().phoneNumbers().updatePhoneNumber("phone number id", pausePhoneNumber);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_number = Mailersend::SMSNumber.new
# Add parameters
ms_sms_number.update(sms_number_id: 'your-sms-number-id', paused: false)
```
[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": "7z3m5jgrogdpyo6n",
"telephone_number": "+1234567890",
"paused": true,
"created_at": "2022-01-01T12:00:00.000000Z"
}
}
```
#### Error [#error-2]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
## Delete an SMS phone number [#delete-an-sms-phone-number]
Delete an SMS phone number with this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/sms-numbers/{sms_number_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-3]
| URL parameter | Type | Required | Limitations | Details |
| --------------- | ------ | -------- | ----------- | ------- |
| `sms_number_id` | string | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$sms = $mailersend->smsNumber->delete('sms_number_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.sms.number.delete("sms_number_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, SmsNumbersBuilder
ms = MailerSendClient()
request = (SmsNumbersBuilder()
.sms_number_id("sms-number-id")
.build_delete_request())
response = ms.sms_numbers.delete(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()
numberID := "number-id"
_, err := ms.SmsNumber.Delete(ctx, numberID)
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 deleteSmsPhoneNumber() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
boolean result = ms.sms().phoneNumbers().deletePhoneNumber("phone number id");
System.out.println(result);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_number = Mailersend::SMSNumber.new
# Add parameters
ms_sms_number.delete(sms_number_id: 'your-sms-number-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-3]
#### Valid [#valid-3]
```http
Response Code: 204 OK
Response Body: [EMPTY]
```
#### Error [#error-3]
```http
Response Code: 404 Not Found
```
# Recipients (/api/v1/sms/recipients)
Get information about SMS recipients.
## Get a list of SMS recipients [#get-a-list-of-sms-recipients]
Get a list of SMS recipients information with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-recipients
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `status` | `string` | no | `active`, `opt_out` | |
| `sms_number_id` | `string` | no | | |
| `page` | `int` | no | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsRecipientParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipientParams = (new SmsRecipientParams())
->setSmsNumberId('sms_number_id')
->setStatus('opt_out')
->setPage(3)
->setLimit(15);
$smsRecipients = $mailersend->smsRecipient->getAll($smsRecipientParams);
```
[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.sms.recipient.list({
sms_number_id: "sms_number_id",
status: "active",
limit: 10,
page: 1,
})
.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, SmsRecipientsBuilder
from mailersend.models.sms_recipients import SmsRecipientStatus
ms = MailerSendClient()
request = (SmsRecipientsBuilder()
.sms_number_id("sms-number-id")
.status(SmsRecipientStatus.ACTIVE)
.page(1)
.limit(25)
.build_list_request())
response = ms.sms_recipients.list_sms_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.SmsRecipientOptions{SmsNumberId: "sms-number-id"}
_, _, err := ms.SmsRecipient.List(context.TODO(), 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.sms.recipients.SmsRecipient;
import com.mailersend.sdk.sms.recipients.SmsRecipientList;
public void getSmsRecipients() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsRecipientList list = ms.sms().recipients().getRecipients();
for (SmsRecipient recipient : list.recipients) {
System.out.println(recipient.id);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_recipient = Mailersend::SMSRecipient.new
# Add parameters
ms_sms_recipient.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": "62347d2be979fd275c0afd34",
"number": "+1234567890",
"status": "active",
"created_at": "2022-01-01T12:00:0003.000000Z"
},
...
]
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
## Get an SMS recipient [#get-an-sms-recipient]
Get information about a specific SMS recipient with this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-recipients/{sms_recipient_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------------ | ------ | -------- | ----------- | ------- |
| `sms_recipient_id` | string | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsRecipient->find('sms_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.sms.recipient.single("sms_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, SmsRecipientsBuilder
ms = MailerSendClient()
request = (SmsRecipientsBuilder()
.sms_recipient_id("recipient-id")
.build_get_request())
response = ms.sms_recipients.get_sms_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()
_, _, err := ms.SmsRecipient.Get(context.TODO(), "sms-recipient-id")
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.sms.recipients.SmsRecipient;
public void getSmsRecipient() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsRecipient recipient = ms.sms().recipients().getRecipient("recipient id");
System.out.println(recipient.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_recipient = Mailersend::SMSRecipient.new
# Add parameters
ms_sms_recipient.get(sms_recipient_id: 'your-sms-recipient-id')
```
[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": "62347d2be979fd275c0afd34",
"number": "+1234567890",
"status": "active",
"created_at": "2022-01-01T12:00:00.000000Z",
"sms": [
{
"id": "62347d2be979fd275c0afd33",
"from": "+1234567890",
"to": "+1234567890",
"text": "Lorem Ipsum is simply dummy text",
"status": "delivered",
"segment_count": 1,
"error_type": null,
"error_description": null,
"created_at": "2022-01-01T12:00:00.000000Z"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 404 Not Found
```
## Update a single SMS recipient [#update-a-single-sms-recipient]
Update a specific SMS recipient with this `PUT` request:
```http
PUT https://api.mailersend.com/v1/sms-recipients/{sms_recipient_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
| URL parameter | Type | Required | Limitations | Details |
| ------------------ | ------ | -------- | ----------- | ------- |
| `sms_recipient_id` | string | yes | | |
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | ------------------- | ------- |
| `status` | `string` | yes | `active`, `opt_out` | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsRecipient->update('sms_recipient_id', $status = 'opt_out');
```
[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.sms.recipient.list({
sms_number_id: "sms_number_id",
status: "active",
limit: 10,
page: 1,
})
.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, SmsRecipientsBuilder
from mailersend.models.sms_recipients import SmsRecipientStatus
ms = MailerSendClient()
request = (SmsRecipientsBuilder()
.sms_recipient_id("recipient-id")
.build_update_request(SmsRecipientStatus.OPT_OUT))
response = ms.sms_recipients.update_sms_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()
options := &mailersend.SmsRecipientSettingOptions{
Id: "sms-recipient-id",
Status: "opt_out",
}
_, _, err := ms.SmsRecipient.Update(context.TODO(), 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.sms.recipients.SmsRecipient;
public void updateSmsRecipient() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
String status = "opt_out";
SmsRecipient recipient = ms.sms().recipients().updateRecipient("recipient id", status);
System.out.println(recipient.status);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Recipient class
ms_sms_recipient = Mailersend::SMSRecipient.new
# Add parameters
ms_sms_recipient.update(sms_recipient_id: 'your-sms-recipient-id', status: 'opt_out')
```
[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": "62347d2be979fd275c0afd34",
"number": "+1234567890",
"status": "opt_out",
"created_at": "2022-01-01T12:00:0003.000000Z"
}
}
```
#### Error [#error-2]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validations errors](/../../general#validation-errors)*
# Webhooks (/api/v1/sms/webhooks)
SMS Webhooks allow you to subscribe to real-time notifications about various SMS events that occur in MailerSend.
You can create a SMS webhook directly from your MailerSend account and listen for events so your integration can automatically trigger reactions.
## SMS Webhooks overview [#sms-webhooks-overview]
### Setup [#setup]
Currently, you can create a SMS webhook using the API endpoints listed below or directly from your account. [Read more about webhooks](https://www.mailersend.com/help/webhooks).
### URL validation [#url-validation]
When creating or updating a webhook, MailerSend will send a test request to the provided URL to verify that it is reachable. The endpoint must return a `2xx` response for the webhook to be saved successfully.
The test request uses the following payload:
```json
{
"type": "webhook.test",
"message": "This is a ping test message",
"created_at": "2026-03-27T07:24:20.577080Z"
}
```
This test request is signed with a fixed test secret: `test_Am3L1GuOIc4blLUuHqAPxxwkZaJyEk8G`. Use it to verify the signature of incoming test requests.
### Available events [#available-events]
These are all the events you can listen to and send a notification for.
| Event | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `sms.sent` | Fired when your SMS is sent from our sending servers. We are now waiting for a response from the receiving servers. |
| `sms.delivered` | Fired when your SMS is successfully delivered with no errors. |
| `sms.failed` | Fired when your SMS failed to deliver. |
### Payload example [#payload-example]
Our responses contain fat payloads, including the information about the event-related object, so there is no need to make an additional API request.
An example of `sms.sent` event:
```
{
"type": "sms.sent",
"sms_number_id": "7z3m5jgrogdpyo6n",
"created_at": "2022-01-01T12:00:00.000000Z",
"sms_webhook_id": "7z3m5jgrogdpyo6n",
"url": "https://www.mailersend.com/webhook",
"data": {
"from": "+12345678901",
"to": "+98765432109",
"created_at": "2022-01-01T12:00:00.000000Z",
"status": "sent",
"sms_message_id": "6244233a7e194137e70e3bd2",
"sms": {
"id": "6244233a7e194137e70e3bd2",
"from": "+12345678901",
"to": "+98765432109",
"text": "Lorem Ipsum is simply dummy text",
"status": "sent",
"segment_count": 1,
"error_type": null,
"error_description": null,
"created_at": "2022-01-01T12:00:00.000000Z",
"recipient": {
"id": "6244233a7e194137e70e3bd2",
"number": "+98765432109",
"status": "active",
"created_at": "2022-01-01T12:00:00.000000Z"
}
}
}
}
```
### Security [#security]
Webhook requests made by MailerSend include a `Signature` header. It contains a string generated by hashing the data sent to your webhook endpoint with an individual Signing Secret. A signing secret is a random string that is generated when you create a webhook.
**Verifying a signature:**
```php
// $signature - a header sent by MailerSend, please refer to your framework
// or PHP manual on how to read the Signature header
// $requestContent - please refer to your framework or PHP manual on how to read the request content
$computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
return hash_equals($signature, $computedSignature);
```
If your endpoint is unreachable or returns a non-2xx response, MailerSend automatically retries with exponential backoff for up to about 3 days. While your webhook is failing we'll send escalating email notifications. If the endpoint stays down too long, the webhook is automatically paused. You can re-enable it from your dashboard at any time.
### Retrying failed webhooks [#retrying-failed-webhooks]
When your webhook receives a response other than a `2xx` code from your endpoint URL, or if the endpoint doesn’t respond within 3 seconds, it will show up as a failed attempt in the log section of your webhook. If it receives a `2xx`, then it will show as a success.
If a webhook call fails, MailerSend automatically retries with exponential backoff for up to about 3 days.
Some failures are considered unrecoverable and aren't retried. Examples include `4xx` client errors (other than `429`) and DNS resolution failures. In these cases only a single attempt is logged, so verify your endpoint URL is reachable before relying on retries.
### Useful tools [#useful-tools]
[Webhook.site](https://webhook.site/) or [Pipedream.com](https://pipedream.com/) are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.
## Get a list of SMS webhooks [#get-a-list-of-sms-webhooks]
If you want to retrieve information about SMS webhooks, use this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-webhooks
```
#### Request parameters \[!toc] [#request-parameters-toc]
| Parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | --------------------- | ------------- |
| `sms_number_id` | `string` | yes | | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
| `page` | `int` | no | Min: `1` | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsWebhook->get('sms_number_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.sms.webhook.list("sms_number_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, SmsWebhooksBuilder
ms = MailerSendClient()
request = (SmsWebhooksBuilder()
.sms_number_id("sms-number-id")
.build_list_request())
response = ms.sms_webhooks.list_sms_webhooks(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.ListSmsWebhookOptions{
SmsNumberId: "sms-number-id",
}
_, _, err := ms.SmsWebhook.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.sms.webhooks.SmsWebhook;
import com.mailersend.sms.webhooks.SmsWebhookList;
public void getSmsWebhooks() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsWebhookList list = ms.sms().webhooks().getWebhooks("phone number id");
for (SmsWebhook webhook : list.webhooks) {
System.out.println(webhook.id);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new
# Add parameters
ms_sms_webhooks.list(sms_number_id: 'your-sms-number-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
## Get a single SMS webhook [#get-a-single-sms-webhook]
To retrieve information about a single SMS webhook, use this `GET` request:
```http
GET https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL Parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_webhook_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsRecipients = $mailersend->smsWebhook->find('sms_webhook_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.sms.webhook.single("sms_webhook_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, SmsWebhooksBuilder
ms = MailerSendClient()
request = (SmsWebhooksBuilder()
.sms_webhook_id("webhook-id")
.build_get_request())
response = ms.sms_webhooks.get_sms_webhook(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()
_, _, err := ms.SmsWebhook.Get(ctx, "sms-webhook-id")
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.sms.webhooks.SmsWebhook;
public void getSmsWebhook() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsWebhook webhook = ms.sms().webhooks().getWebhook("webhook id");
System.out.println(webhook.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new
# Add parameters
ms_sms_webhooks.get_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
## Create an SMS webhook [#create-an-sms-webhook]
Create a SMS webhook using this `POST` request:
```http
POST https://api.mailersend.com/v1/sms-webhooks/
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| --------------- | --------- | -------- | ------------------ | ------------------------------ |
| `url` | `url` | yes | Max: `191`, unique | |
| `name` | `string` | yes | Max: `191` | |
| `events` | `array` | yes | | |
| `enabled` | `boolean` | optional | | |
| `sms_number_id` | `string` | yes | | Existing hashed SMS number ID. |
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsWebhookParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsWebhookParams = (new SmsWebhookParams())
->setSmsNumberId('sms_number_id')
->setName('Name')
->setUrl('https://mailersend.com/sms_webhook')
->setEvents(['sms.sent', 'sms.delivered', 'sms.failed'])
->setEnabled(false);
$smsRecipients = $mailersend->smsWebhook->create($smsWebhookParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { MailerSend, SmsWebhook, SmsWebhookEventType } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const smsWebhook = new SmsWebhook()
.setName("Sms Webhook")
.setUrl("https:://yourapp.com/hook")
.setSmsNumberId("sms_number_id")
.setEnabled(true)
.setEvents([SmsWebhookEventType.SENT, SmsWebhookEventType.DELIVERED])
mailerSend.sms.webhook.create(smsWebhook)
.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, SmsWebhooksBuilder
from mailersend.models.sms_webhooks import SmsWebhookEvent
ms = MailerSendClient()
request = (SmsWebhooksBuilder()
.from_number("sms-number-id")
.url("https://webhook.example.com/sms")
.name("SMS Webhook")
.add_event(SmsWebhookEvent.SMS_SENT)
.add_event(SmsWebhookEvent.SMS_DELIVERED)
.add_event(SmsWebhookEvent.SMS_FAILED)
.enabled(True)
.build_create_request())
response = ms.sms_webhooks.create_sms_webhook(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()
events := []string{"sms.sent"}
options := &mailersend.CreateSmsWebhookOptions{
SmsNumberId: "sms-number-id",
Name: "Webhook",
Events: events,
URL: "https://test.com",
Enabled: mailersend.Bool(false),
}
_, _, err := ms.SmsWebhook.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.exceptions.MailerSendException;
import com.mailersend.sms.webhooks.SmsWebhook;
public void createSmsWebhook() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsWebhook webhook = ms.sms().webhooks().builder()
.addEvent("sms.sent")
.name("sms webhook")
.url("https://example.com")
.createWebhook("sms phone number id");
System.out.print(webhook.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new
# Add parameters
ms_sms_webhooks.settings =
{
'sms_number_id' => 'your-sms-number-id',
'name' => 'your-name',
'url' => 'https://your-url.com',
'events' => ['sms.sent', 'sms.delivered']
}
puts ms_sms_webhooks.add_sms_webhook_route
```
[More examples](https://github.com/mailersend/mailersend-ruby)
## Update a single SMS webhook [#update-a-single-sms-webhook]
Update a SMS webhook using this `PUT` request:
```http
PUT https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
```
### Request Parameters \[!toc] [#request-parameters-toc-3]
| URL Parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_webhook_id` | `string` | yes | | |
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| -------------- | --------- | -------- | ----------- | ------- |
| `url` | `url` | optional | Max: `191` | |
| `name` | `string` | optional | Max: `191` | |
| `events` | `array` | optional | | |
| `enabled` | `boolean` | optional | | |
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsWebhookParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$smsWebhookParams = (new SmsWebhookParams())
->setSmsNumberId('sms_number_id')
->setName('Name')
->setUrl('https://mailersend.com/sms_webhook')
->setEvents(['sms.sent', 'sms.delivered', 'sms.failed'])
->setEnabled(false);
$smsRecipients = $mailersend->smsWebhook->update('sms_webhook_id', $smsWebhookParams);
```
[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.sms.webhook.update("sms_webhook_id", {
name: "Webhook",
url: "https:://yourapp.com/hook",
enabled: ["sms.sent", "sms.delivered", "sms.failed"],
enabled: true
})
.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, SmsWebhooksBuilder
from mailersend.models.sms_webhooks import SmsWebhookEvent
ms = MailerSendClient()
request = (SmsWebhooksBuilder()
.sms_webhook_id("webhook-id")
.name("Updated SMS Webhook")
.url("https://new-webhook.example.com/sms")
.events([SmsWebhookEvent.SMS_DELIVERED, SmsWebhookEvent.SMS_FAILED])
.enabled(False)
.build_update_request())
response = ms.sms_webhooks.update_sms_webhook(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()
events := []string{"sms.sent"}
options := &mailersend.UpdateSmsWebhookOptions{
Id: "sms-webhook-id",
Name: "Webhook",
Events: events,
Enabled: mailersend.Bool(true),
URL: "https://test.com",
}
_, _, err := ms.SmsWebhook.Update(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.sms.webhooks.SmsWebhook;
public void updateSmsWebhook() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
SmsWebhook webhook = ms.sms().webhooks().builder()
.name("sms updated webhook")
.updateWebhook("webhook id");
System.out.print(webhook.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new
# Add parameters
ms_sms_webhooks.settings =
{
'sms_number_id' => 'your-sms-number-id',
'name' => 'your-name',
'url' => 'https://your-url.com',
'events' => ['sms.sent', 'sms.delivered']
}
puts ms_sms_webhooks.update_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
## Delete an SMS webhook [#delete-an-sms-webhook]
Delete a SMS webhook using this `DELETE` request:
```http
DELETE https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
```
### Request Parameters \[!toc] [#request-parameters-toc-4]
| URL Parameter | Type | Required | Limitations | Details |
| ---------------- | -------- | -------- | ----------- | ------- |
| `sms_webhook_id` | `string` | yes | | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->smsWebhook->delete('sms_webhook_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.sms.webhook.delete("sms_webhook_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, SmsWebhooksBuilder
ms = MailerSendClient()
request = (SmsWebhooksBuilder()
.sms_webhook_id("webhook-id")
.build_delete_request())
response = ms.sms_webhooks.delete_sms_webhook(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()
_, err := ms.SmsWebhook.Delete(ctx, "sms-webhook-id")
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 deleteSmsWebhook() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
boolean result = ms.sms().webhooks().deleteWebhook("webhook id");
System.out.print(result);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new
# Add parameters
ms_sms_webhooks.delete_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
# Email Verification (/api/v1/verification/email)
This endpoint allows you to verify emails through the MailerSend Email API.
## Verify an email [#verify-an-email]
If you want to verify a single email, use this `POST` request:
```http
POST https://api.mailersend.com/v1/email-verification/verify
```
#### Request parameters \[!toc] [#request-parameters-toc]
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | -------- | -------- | ----------- | ------- |
| `email` | `string` | yes | Max: `320` | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->verifyEmail('test@example.com');
```
[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.emailVerification.verifyEmail("test@example.com")
.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()
options := &mailersend.SingleEmailVerificationOptions{
Email: "john@doe.com"
}
_, _, err := ms.EmailVerification.VerifySingle(ctx, options)
if err != nil {
log.Fatal(err)
}
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.verify_an_email(email: 'test@example.com')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
```json
{
"status": "valid"
}
```
#### Not enough credits error [#not-enough-credits-error]
```http
Response Code: 402 Payment Required
Response Headers:
content-type: application/json
```
```json
{
"message": "Not enough credits. Credits required: 1"
}
```
### Verification results [#verification-results]
The possible outcome of an email validation can be grouped in 3 categories: **Valid**, **Risky** and **Do Not Send**.
#### Valid [#valid-1]
| Result | Description |
| ------- | ---------------------- |
| `valid` | Email is safe to send. |
#### Risky [#risky]
| Result | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `catch_all` | Recipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person. |
| `mailbox_full` | Recipient’s inbox is full and may not be able to receive new emails. |
| `role_based` | Email is role-based and may not be associated with a single, specific person but a group of people. |
| `unknown` | We are unable to determine if the email is valid or not valid. |
| `failed` | We could not perform the check due to timeouts. Verify the email by importing a list. |
#### Do Not Send [#do-not-send]
| Result | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `syntax_error` | The email address is not valid. |
| `typo` | The email address has a typo. Correct the email address and retest. |
| `mailbox_not_found` | Recipient’s inbox does not exist. |
| `disposable` | The email address is a temporary inbox and should be removed from your lists. |
| `mailbox_blocked` | The email address’ mailbox is blocked by its service provider due to poor sending practices. |
*See - [Validation errors](/../../general#validation-errors)*
## Verify an email (Async) [#verify-an-email-async]
Check a single email and receive the result asynchronously to avoid delays and timeouts, use this `POST` request:
```http
POST https://api.mailersend.com/v1/email-verification/verify-async
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| JSON parameter | Type | Required | Limitations | Details |
| -------------- | -------- | -------- | ----------- | ------- |
| `email` | `string` | yes | Max: `320` | |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->verifyAsync('test@example.com');
```
[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.emailVerification.verifyEmailAsync("test@example.com")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
### Responses [#responses-1]
#### Valid [#valid-2]
```json
{
"id": "67c83bf24a5d02568029ee10",
"address": "test@email.com",
"status": "queued",
"result": null,
"error": null
}
```
#### Not enough credits error [#not-enough-credits-error-1]
```http
Response Code: 402 Payment Required
Response Headers:
content-type: application/json
```
```json
{
"message": "Not enough credits. Credits required: 1"
}
```
*See - [Validation errors](/../../general#validation-errors)*
## Get async email verification status [#get-async-email-verification-status]
If you want to retrieve information about an async email verification status, use this `GET` request or [Receive via webhook](/api/v1/account/webhooks#available-events):
```http
GET https://api.mailersend.com/v1/email-verification/verify-async/{email_verification_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-2]
| URL parameter | Type | Required | Limitations | Details |
| ----------------------- | -------- | -------- | ----------- | ------- |
| `email_verification_id` | `string` | yes | | |
### Check verification status [#check-verification-status]
You can use this endpoint to check the verification status, with the following possible status:
| Status | Description |
| ----------- | -------------------------------------------------------- |
| `queued` | The verification process is ongoing. |
| `completed` | The verification process has finished successfully. |
| `failed` | The verification process has run into an internal error. |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->getVerifyAsyncResult('email_verification_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.emailVerification.getVerifyEmailAsyncStatus("email_verification_id")
.then((response) => console.log(response.body))
.catch((error) => console.log(error.body));
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
### Responses [#responses-2]
#### Valid [#valid-3]
```json
{
"id": "67c8863ce2fbd4fc8a7611cc",
"address": "test@email.com",
"status": "completed",
"result": "unknown",
"error": null
}
```
### Response fields [#response-fields]
| Field | Type | Details |
| --------- | -------------- | ---------------------------------------------------------------------- |
| `id` | `string` | The unique identifier of the async verification. |
| `address` | `string` | The email address that was verified. |
| `status` | `string` | The current verification status (`queued`, `completed`, or `failed`). |
| `result` | `string\|null` | The verification result once completed. `null` while still processing. |
| `error` | `string\|null` | Error message when `status` is `failed`. `null` otherwise. |
## Get all lists [#get-all-lists]
Get all email verifications lists with this `GET` request:
```http
GET https://api.mailersend.com/v1/email-verification
```
#### Request parameters \[!toc] [#request-parameters-toc-3]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | ----- | -------- | --------------------- | ------------- |
| `page` | `int` | no | Min: `1` | |
| `limit` | `int` | no | Min: `10`, Max: `100` | Default: `25` |
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->getAll($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.emailVerification.list({
limit: 10,
page: 1
})
.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, EmailVerificationBuilder
ms = MailerSendClient()
request = EmailVerificationBuilder().build_list_request()
response = ms.email_verification.list_verification_lists(request)
for verification_list in response.data:
print(f"List: {verification_list.name}, Status: {verification_list.status}")
```
[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.ListEmailVerificationOptions{
Page: 1,
Limit: 25,
}
_, _, err := ms.EmailVerification.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.mailsend.sdk.emailverification.EmailVerificationList;
import com.mailsend.sdk.emailverification.EmailVerificationLists;
public void getLists() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
EmailVerificationLists lists = ms.emailVerification().getLists();
for (EmailVerificationList list : lists.lists) {
System.out.println(list.id);
System.out.println(list.name);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.list(page: 1, limit: 10)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-3]
#### Valid [#valid-4]
```json
{
"data": [
{
"id": "n3k6d1jr1eq50x4v",
"name": "Example List",
"total": 0,
"verification_started": null,
"verification_ended": null,
"created_at": "2022-07-19T15:11:18.000000Z",
"updated_at": "2022-07-19T15:11:18.000000Z",
"status": {
"name": "uploading",
"count": 0
},
"source": "api",
"statistics": {
"valid": 0,
"catch_all": 0,
"mailbox_full": 0,
"role_based": 0,
"unknown": 0,
"syntax_error": 0,
"typo": 0,
"mailbox_not_found": 0,
"disposable": 0,
"mailbox_blocked": 0,
"failed": 0
}
}
],
"links": {
"first": "http:\/\/localhost:8080\/api\/v1\/email-verification?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "http:\/\/localhost:8080\/api\/v1\/email-verification",
"per_page": 25,
"to": 1
}
}
```
## Get a single list [#get-a-single-list]
If you want to retrieve information about a single email verification list, use this `GET` request:
```http
GET https://api.mailersend.com/v1/email-verification/{email_verification_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-4]
| URL parameter | Type | Required | Limitations | Details |
| ----------------------- | -------- | -------- | ----------- | ------- |
| `email_verification_id` | `string` | yes | | |
| Query parameter | Type | Required | Limitations | Details |
| --------------- | --------- | -------- | -------------------- | ----------------------------------------------------------------------------- |
| `detailed` | `boolean` | no | | When true, response includes an `emails` object with paginated email results. |
| `page` | `integer` | no | Min: `1` | Only relevant when `detailed=true`. |
| `limit` | `integer` | no | Min: `1`, Max: `100` | Only relevant when `detailed=true`. |
### Check verification status [#check-verification-status-1]
You can use this endpoint to check the verification status, with the following possible status:
| Status | Description |
| ----------- | -------------------------------------------------------- |
| `uploading` | The email addresses are being uploaded to our system. |
| `created` | The list has been created and is ready to be verified. |
| `verifying` | The verification process is ongoing. |
| `verified` | The verification process has finished successfully. |
| `failed` | The verification process has run into an internal error. |
| `canceled` | The verification process was canceled. |
| `paused` | The verification process is paused. |
You can also check how many emails have been verified by consulting the `count` property of the status object.
Example of status in the payload:
```json
"status": {
"name": "verifying",
"count": 5
}
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->find('email_verification_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.emailVerification.single("email_verification_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, EmailVerificationBuilder
ms = MailerSendClient()
request = (EmailVerificationBuilder()
.verification_list_id("list-id")
.build_get_request())
response = ms.email_verification.get_verification_list(request)
print(f"List name: {response.name}")
```
[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()
_, _, err := ms.EmailVerification.Get(ctx, "email-verification-id")
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.mailsend.sdk.emailverification.EmailVerificationList;
public void getList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
EmailVerificationList list = ms.emailVerification().getList("list id");
System.out.println(list.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.get_single_list(email_verification_id: 'your-email-verification-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-4]
#### Valid [#valid-5]
```json
{
"data": {
"id": "n3k6d1jr1eq50x4v",
"name": "Example List",
"total": 0,
"verification_started": null,
"verification_ended": null,
"created_at": "2022-07-19T15:11:18.000000Z",
"updated_at": "2022-07-19T15:11:18.000000Z",
"status": {
"name": "uploading",
"count": 0
},
"source": "api",
"statistics": {
"valid": 0,
"catch_all": 0,
"mailbox_full": 0,
"role_based": 0,
"unknown": 0,
"syntax_error": 0,
"typo": 0,
"mailbox_not_found": 0,
"disposable": 0,
"mailbox_blocked": 0,
"failed": 0
}
}
}
```
#### Valid with detailed=true [#valid-with-detailedtrue]
```json
{
"data": {
"id": "n3k6d1jr1eq50x4v",
"name": "Example List",
"total": 2,
"verification_started": "2022-07-19T15:24:19.000000Z",
"verification_ended": "2022-07-19T15:30:00.000000Z",
"created_at": "2022-07-19T15:11:18.000000Z",
"updated_at": "2022-07-19T15:30:00.000000Z",
"status": {
"name": "verified",
"count": 2
},
"source": "api",
"statistics": {
"valid": 1,
"catch_all": 0,
"mailbox_full": 0,
"role_based": 0,
"unknown": 0,
"syntax_error": 0,
"typo": 1,
"mailbox_not_found": 0,
"disposable": 0,
"mailbox_blocked": 0,
"failed": 0
},
"emails": {
"data": [
{
"address": "example1@mail.com",
"result": "typo"
},
{
"address": "example2@gmail.com",
"result": "valid"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total": 2,
"last_page": 1,
"from": 1,
"to": 2
},
"links": {
"first": "https://api.mailersend.com/v1/email-verification/n3k6d1jr1eq50x4v?detailed=true&page=1",
"last": "https://api.mailersend.com/v1/email-verification/n3k6d1jr1eq50x4v?detailed=true&page=1",
"prev": null,
"next": null
}
}
}
}
```
#### Error [#error]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Create a list [#create-a-list]
If you want to add a new email verification list, use this `POST` request:
```http
POST https://api.mailersend.com/v1/email-verification
```
### Request body \[!toc] [#request-body-toc]
```json
{
"name": "Example List",
"emails": [
"example1@mail.com",
"example2@mail.com"
]
}
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\EmailVerificationParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$emailVerificationParams = (new EmailVerificationParams('file.csv'))
->setEmailAddresses(['test@mail.com']);
$mailersend->emailVerification->create($emailVerificationParams);
// Optionally start verification immediately or attach to an existing list
$emailVerificationParams = (new EmailVerificationParams('file.csv'))
->setEmailAddresses(['test@mail.com'])
->setListId('existing_list_id')
->setVerify(true);
$mailersend->emailVerification->create($emailVerificationParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { EmailVerification, MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const emailVerification = new EmailVerification()
.setName("List example")
.setEmails([
"info@mailersend.com",
"test@mailersend.com"
]);
mailerSend.emailVerification.create(emailVerification)
.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, EmailVerificationBuilder
ms = MailerSendClient()
request = (EmailVerificationBuilder()
.name("My Verification List")
.emails(["test1@example.com", "test2@example.com"])
.build_create_request())
response = ms.email_verification.create_verification_list(request)
print(f"Created list with ID: {response.id}")
```
[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.CreateEmailVerificationOptions{
Name: "Email Verification List ",
Emails: []string{"your@client.com", "your@client.eu"},
}
_, _, err := ms.EmailVerification.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.exceptions.MailerSendException;
import com.mailsend.sdk.emailverification.EmailVerificationList;
public void createList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
EmailVerificationList list = ms.emailVerification().builder()
.name("Test email verification")
.addEmail("info@example.com")
.addEmail("info1@example.com")
.addEmail("info2@example.com")
.create();
System.out.println(list.id);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.create_a_list(name: "name-your-list", emails: ["example@email.com"])
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Request Parameters \[!toc] [#request-parameters-toc-5]
*JSON parameters are provided in dot notation*
| JSON Parameter | Type | Required | Limitations | Details |
| -------------- | --------- | -------------------------- | ---------------------- | -------------------------------------------------------- |
| `name` | `string` | required\_without:list\_id | Max: `191` | |
| `list_id` | `string` | no | | ID of an existing verification list to append emails to. |
| `emails` | `array` | yes | Min: `1`, Max: `10000` | |
| `emails.*` | `string` | yes | Max: `320` | |
| `verify` | `boolean` | no | | If true, immediately starts verification after upload. |
### Responses [#responses-5]
| Response Key | Type | Details |
| ------------ | ------ | --------------------------------- |
| data | object | EmailVerification object created. |
#### Valid [#valid-6]
```http
Response Code: 201 CREATED
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "n3k6d1jr1eq50x4v",
"name": "Example List",
"total": 0,
"verification_started": null,
"verification_ended": null,
"created_at": "2022-07-19T15:11:18.000000Z",
"updated_at": "2022-07-19T15:11:18.000000Z",
"status": {
"name": "uploading",
"count": 0
},
"source": "api",
"statistics": {
"valid": 0,
"catch_all": 0,
"mailbox_full": 0,
"role_based": 0,
"unknown": 0,
"syntax_error": 0,
"typo": 0,
"mailbox_not_found": 0,
"disposable": 0,
"mailbox_blocked": 0,
"failed": 0
}
}
}
```
#### Invalid [#invalid]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Verify a list [#verify-a-list]
If you want to verify an email verification list, use this `GET` request:
```http
GET https://api.mailersend.com/v1/email-verification/{email_verification_id}/verify
```
#### Request parameters \[!toc] [#request-parameters-toc-6]
| URL parameter | Type | Required | Limitations | Details |
| ----------------------- | -------- | -------- | ----------- | ------- |
| `email_verification_id` | `string` | yes | | |
> **Note:** Sending this request while an email list is already being verified (status is `verifying`) will not queue another verification. Also, sending this request when the email list is verified (status is `verified`) will trigger a new verification.
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->verify('email_verification_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.emailVerification.verifyList("email_verification_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, EmailVerificationBuilder
ms = MailerSendClient()
request = (EmailVerificationBuilder()
.verification_list_id("list-id")
.build_verify_request())
response = ms.email_verification.verify_list(request)
print(f"Verification started: {response.message}")
```
[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()
_, _, err := ms.EmailVerification.Verify(ctx, "email-verification-id")
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.mailsend.sdk.emailverification.EmailVerificationList;
public void verifyList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
EmailVerificationList list = ms.emailVerification().verifyList("list id");
System.out.println(list.status.name);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.verify_a_list(email_verification_id: 'your-email-verification-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-6]
#### Valid [#valid-7]
```json
{
"data": {
"id": "n3k6d1jr1eq50x4v",
"name": "Example List",
"total": 2,
"verification_started": "2022-07-19T15:24:19.000000Z",
"verification_ended": null,
"created_at": "2022-07-19T15:11:18.000000Z",
"updated_at": "2022-07-19T15:24:19.000000Z",
"status": {
"name": "verifying",
"count": 0
},
"source": "api",
"statistics": {
"valid": 0,
"catch_all": 0,
"mailbox_full": 0,
"role_based": 0,
"unknown": 0,
"syntax_error": 0,
"typo": 0,
"mailbox_not_found": 0,
"disposable": 0,
"mailbox_blocked": 0,
"failed": 0
}
}
}
```
#### Still uploading error [#still-uploading-error]
```http
Response Code: 403 Forbidden
Response Headers:
content-type: application/json
```
```json
{
"message": "The email addresses are still being uploaded, wait for the upload to finish to continue."
}
```
#### Not enough credits error [#not-enough-credits-error-2]
```http
Response Code: 403 Forbidden
Response Headers:
content-type: application/json
```
```json
{
"message": "You do not have enough credits to perform this operation."
}
```
*See - [Validation errors](/../../general#validation-errors)*
## Get list results [#get-list-results]
If you want to get the result for each individual email of an email verification list, use this `GET` request:
```http
GET https://api.mailersend.com/v1/email-verification/{email_verification_id}/results
```
#### Request parameters \[!toc] [#request-parameters-toc-7]
| URL parameter | Type | Required | Limitations | Details |
| ----------------------- | -------- | -------- | ----------- | ------- |
| `email_verification_id` | `string` | yes | | |
| Query parameter | Type | Required | Limitations | Details | |
| --------------- | -------- | -------- | ----------------------------------------------------------------- | ------------- | - |
| `page` | `int` | no | Min: `1` | | |
| `limit` | `int` | no | Min: `10`, Max: `500` | Default: `25` | |
| `results` | `array` | no | | | |
| `results.*` | `string` | yes | Must be one of the [verification results](#verification-results). | | |
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\EmailVerificationParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->emailVerification->getResults(
$emailVerificationId = 'email_verification_id',
$page = 1,
$limit = 10,
$results = [
EmailVerificationParams::TYPO,
EmailVerificationParams::CATCH_ALL,
],
);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import 'dotenv/config';
import { EmailVerificationResultType, MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.emailVerification.getListResult("email_verification_id",{
limit: 10,
page: 1,
results: [EmailVerificationResultType.CATCH_ALL, EmailVerificationResultType.DISPOSABLE]
})
.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, EmailVerificationBuilder
ms = MailerSendClient()
request = (EmailVerificationBuilder()
.verification_list_id("list-id")
.build_results_request())
response = ms.email_verification.get_verification_results(request)
for result in response.data:
print(f"Email: {result.email}, Status: {result.status}")
```
[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.GetEmailVerificationOptions{
EmailVerificationId: "email-verification-id",
Page: 1,
Limit: 25,
}
_, _, err := ms.EmailVerification.GetResults(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.mailsend.sdk.emailverification.ListVerificationResults;
import com.mailsend.sdk.emailverification.VerificationResult;
public void verifyList() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
ListVerificationResults results = ms.emailVerification().verificationResults("list id");
for (VerificationResult result : results.results) {
System.out.println(result.address);
System.out.println(result.result);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
ms_email_verification = Mailersend::EmailVerification.new
ms_email_verification.get_list_results(email_verification_id: 'your-email-verification-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-7]
#### Valid [#valid-8]
```json
{
"data": [
{
"address": "example1@mail.com",
"result": "typo"
},
{
"address": "example2@gmail.com",
"result": "mailbox_not_found"
}
],
"links": {
"first": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results?1=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results",
"per_page": 25,
"to": 2
}
}
```
#### Error [#error-1]
```http
Response Code: 422 Unprocessable Entity
```
*See - [Validation errors](/../../general#validation-errors)*
## Verification results [#verification-results-1]
The possible outcome of an email validation can be grouped in 3 categories: **Valid**, **Risky** and **Do Not Send**.
### Valid [#valid-9]
| Result | Description |
| ------- | ---------------------- |
| `valid` | Email is safe to send. |
### Risky [#risky-1]
| Result | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `catch_all` | Recipient’s mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person. |
| `mailbox_full` | Recipient’s inbox is full and may not be able to receive new emails. |
| `role_based` | Email is role-based and may not be associated with a single, specific person but a group of people. |
| `unknown` | We are unable to determine if the email is valid or not valid. |
| `failed` | We could not perform the check due to timeouts. Verify the email by importing a list. |
### Do Not Send [#do-not-send-1]
| Result | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `syntax_error` | The email address is not valid. |
| `typo` | The email address has a typo. Correct the email address and retest. |
| `mailbox_not_found` | Recipient’s inbox does not exist. |
| `disposable` | The email address is a temporary inbox and should be removed from your lists. |
| `mailbox_blocked` | The email address’ mailbox is blocked by its service provider due to poor sending practices. |
# Activities (/api/v1/whatsapp/activities)
An activity is a single status event of an [item](/api/v1/whatsapp/items), the delivery of a message to one recipient. One item has an activity for every status it moved through, so a delivered and read message appears once as `queued`, once as `sent`, once as `delivered` and once as `read`. See [WhatsApp status list](/general#whatsapp-status-list).
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
WhatsApp activity is kept for 7 days. An activity older than that is no longer listed.
## Get a list of WhatsApp activities [#get-a-list-of-whatsapp-activities]
Get a list of the status events of your WhatsApp messages with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/activities
```
Activities are returned newest first. To get the activity of one item in status order (`queued`, `sent`, `delivered`, `read`, `failed`), use [`GET` /v1/whatsapp/items/\{item\_id}](/api/v1/whatsapp/items#get-a-whatsapp-item).
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `whatsapp_item_id` | `string` | no | | The ID of the item the activities belong to. |
| `whatsapp_message_id` | `string` | no | | The ID of the message the activities belong to. |
| `recipient` | `string` | no | | The recipient's phone number in international format, WhatsApp username or BSUID. See [Filtering](#filtering). |
| `type[]` | `string[]` | no | Possible values: `queued`, `sent`, `delivered`, `read`, `failed` | Array only. Multiple values are combined with `OR`. |
| `date_from` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be lower than `date_to`. No fractional seconds: `2026-10-14T00:00:00.000Z` is rejected. | Unix timestamp: `1791936000`, ISO 8601 datetime: `2026-10-14T00:00:00Z` or datetime: `2026-10-14 00:00:00`. Exclusive. |
| `date_to` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be higher than `date_from`. No fractional seconds: `2026-10-15T00:00:00.000Z` is rejected. | Unix timestamp: `1792022400`, ISO 8601 datetime: `2026-10-15T00:00:00Z` or datetime: `2026-10-15 00:00:00`. Exclusive. |
| `page` | `int` | no | Min: `1`, Max: `100` | To reach older activities beyond page `100`, narrow `date_from` and `date_to`. |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
#### Filtering \[!toc] [#filtering-toc]
`date_from` and `date_to` are exclusive: only activities created strictly after `date_from` and strictly before `date_to` are returned. Both accept a Unix timestamp, an ISO 8601 datetime with `Z` or an offset such as `2026-10-14T00:00:00+02:00`, or a datetime in `Y-m-d H:i:s` format. A date without a time, such as `2026-10-14`, returns a `422` validation error.
`recipient` accepts a phone number in international format, a WhatsApp username or a BSUID. In phone numbers, spaces, dashes and the leading `+` are ignored, so `+48 600-000-001` and `48600000001` match the same recipient.
`type[]` must be sent as an array, for example `?type[]=delivered&type[]=read`.
An example request that returns the activities of one message:
```http
GET https://api.mailersend.com/v1/whatsapp/activities?whatsapp_message_id=67f91abd69f79df391e9d78d
```
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/activities?whatsapp_message_id=67f91abd69f79df391e9d78d&limit=25' \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappActivityParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappActivityParams = (new WhatsappActivityParams())
->setWhatsappMessageId('message_id')
->setPage(1)
->setLimit(25);
$whatsappActivities = $mailersend->whatsappActivity->getAll($whatsappActivityParams);
```
[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.whatsapp.activity.list({
whatsapp_message_id: "message_id",
limit: 25,
page: 1,
})
.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, WhatsAppActivitiesBuilder
ms = MailerSendClient()
request = (WhatsAppActivitiesBuilder()
.whatsapp_message_id("message-id")
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_activities.list_whatsapp_activities(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.ListWhatsAppActivityOptions{
WhatsAppMessageID: "message-id",
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppActivity.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.whatsapp.activities.WhatsAppActivity;
import com.mailersend.sdk.whatsapp.activities.WhatsAppActivityList;
public void getWhatsAppActivities() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppActivityList list = ms.whatsapp().activities()
.whatsappMessageId("message id")
.page(1)
.limit(25)
.getActivities();
for (WhatsAppActivity activity : list.activities) {
System.out.println(activity.whatsappItemId);
System.out.println(activity.type);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Activities class
ms_whatsapp_activities = Mailersend::WhatsAppActivities.new
# Add parameters
ms_whatsapp_activities.list(whatsapp_message_id: 'your-whatsapp-message-id', page: 1, limit: 25)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data[].id` | `string` | ID of the activity. |
| `data[].whatsapp_item_id` | `string` | ID of the item the activity belongs to. Pass it to [`GET` /v1/whatsapp/items/\{item\_id}](/api/v1/whatsapp/items#get-a-whatsapp-item). |
| `data[].whatsapp_message_id` | `string` | ID of the message the activity belongs to. Pass it to [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message). |
| `data[].whatsapp_account_id` | `string\|null` | The MailerSend sender ID of the phone number the message was sent from. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `data[].from` | `string\|null` | The sender's phone number, or its WhatsApp username when the message was sent from the username or the sender has no phone number, such as one connected with a Meta virtual number. `null` when the sender has neither. |
| `data[].to` | `string` | The recipient's phone number or BSUID. |
| `data[].type` | `string` | The status that was recorded: `queued`, `sent`, `delivered`, `read` or `failed`. |
| `data[].created_at` | `string` | When the status was recorded, in ISO 8601 format. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "6acf9f214069f5eceb882bf1",
"whatsapp_item_id": "67f91abe2202f3705540234a",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000001",
"type": "read",
"created_at": "2026-10-14T12:31:02.000000Z"
},
{
"id": "6acf9f214069f5eceb882bea",
"whatsapp_item_id": "67f91abe2202f3705540234a",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000001",
"type": "delivered",
"created_at": "2026-10-14T12:25:36.000000Z"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/activities?whatsapp_message_id=67f91abd69f79df391e9d78d&limit=25&page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/activities?whatsapp_message_id=67f91abd69f79df391e9d78d&limit=25&page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/activities",
"per_page": 25,
"to": 2
}
}
```
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when a parameter is invalid — including an unknown value in `type[]`, a `date_from` or `date_to` without a time, a `date_to` that is not after `date_from`, or a `page` or `limit` out of range.
*See - [Validation errors](/general#validation-errors)*
# Inbound messages (/api/v1/whatsapp/inbound-messages)
Inbound messages are the messages people send to your WhatsApp phone numbers, including replies to your template messages and button taps. They are also delivered in real time as `whatsapp.inbound` [webhook](/api/v1/whatsapp/webhooks#inbound-messages) events.
The API returns the content of every message type in a single `meta` object, while the webhook payload carries it in a field named after the type. See [Message content](#message-content).
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
Inbound messages are kept for the inbound retention period of your plan: 7, 14 or 30 days. An inbound message older than that is no longer listed, and requesting it returns `404`.
## Get a list of inbound messages [#get-a-list-of-inbound-messages]
Get a list of the WhatsApp messages received by your phone numbers with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/inbound-messages
```
Inbound messages are returned newest first.
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `whatsapp_account_id` | `string` | no | Must be one of your WhatsApp senders. | The MailerSend sender ID of the phone number that received the messages. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `from` | `string` | no | Max: `255` characters | The customer's phone number in international format, or their BSUID. See [Filtering](#filtering). |
| `type[]` | `string[]` | no | Possible values: `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `contacts`, `interactive`, `button`, `order`, `reaction`, `system`, `unknown`, `unsupported` | Array only. Multiple values are combined with `OR`. |
| `date_from` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be lower than `date_to`. No fractional seconds: `2026-10-14T00:00:00.000Z` is rejected. | Unix timestamp: `1791936000`, ISO 8601 datetime: `2026-10-14T00:00:00Z` or datetime: `2026-10-14 00:00:00`. Exclusive. Applied to `received_at`. |
| `date_to` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be higher than `date_from`. No fractional seconds: `2026-10-15T00:00:00.000Z` is rejected. | Unix timestamp: `1792022400`, ISO 8601 datetime: `2026-10-15T00:00:00Z` or datetime: `2026-10-15 00:00:00`. Exclusive. Applied to `received_at`. |
| `page` | `int` | no | Min: `1`, Max: `100` | To reach older messages beyond page `100`, narrow `date_from` and `date_to`. |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
#### Filtering \[!toc] [#filtering-toc]
`date_from` and `date_to` are exclusive: only messages received strictly after `date_from` and strictly before `date_to` are returned. Both accept a Unix timestamp, an ISO 8601 datetime with `Z` or an offset such as `2026-10-14T00:00:00+02:00`, or a datetime in `Y-m-d H:i:s` format. A date without a time, such as `2026-10-14`, returns a `422` validation error.
`from` accepts a phone number in international format, or a BSUID for a customer whose phone number WhatsApp doesn't share. In phone numbers, spaces, dashes and the leading `+` are ignored, so `+48 600-000-001` and `48600000001` match the same customer. A WhatsApp username is not accepted.
`type[]` must be sent as an array, for example `?type[]=text&type[]=image`.
An example request that returns the text and image messages one phone number received over one day:
```http
GET https://api.mailersend.com/v1/whatsapp/inbound-messages?whatsapp_account_id=3enl6x27wmrxrl2v&type[]=text&type[]=image&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z&limit=50
```
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/inbound-messages?whatsapp_account_id=3enl6x27wmrxrl2v&from=48600000001&type[]=text&type[]=image&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z&limit=25' \
--globoff \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappInboundMessageParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappInboundMessageParams = (new WhatsappInboundMessageParams())
->setWhatsappAccountId('whatsapp_account_id')
->setFrom('48600000001')
->setType(['text', 'image'])
->setDateFrom(1790000000)
->setDateTo(1790086400)
->setPage(1)
->setLimit(25);
$whatsappInboundMessages = $mailersend->whatsappInboundMessage->getAll($whatsappInboundMessageParams);
```
[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.whatsapp.inboundMessage.list({
whatsapp_account_id: "whatsapp_account_id",
from: "48600000001",
type: ["text", "image"],
date_from: 1790000000,
date_to: 1790086400,
limit: 25,
page: 1,
})
.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, WhatsAppInboundMessagesBuilder
from datetime import datetime, timedelta
ms = MailerSendClient()
# Get inbound messages from the last day
date_from = int((datetime.now() - timedelta(days=1)).timestamp())
date_to = int(datetime.now().timestamp())
request = (WhatsAppInboundMessagesBuilder()
.whatsapp_account_id("whatsapp-account-id")
.from_number("48600000001")
.type(["text", "image"])
.date_from(date_from)
.date_to(date_to)
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_inbound_messages.list_whatsapp_inbound_messages(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()
from := time.Now().Add(-24 * time.Hour).Unix()
to := time.Now().Unix()
options := &mailersend.ListWhatsAppInboundMessageOptions{
WhatsAppAccountID: "whatsapp-account-id",
From: "48600000001",
Type: []string{"text", "image"},
DateFrom: from,
DateTo: to,
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppInboundMessage.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.whatsapp.inboundmessages.WhatsAppInboundMessage;
import com.mailersend.sdk.whatsapp.inboundmessages.WhatsAppInboundMessageList;
public void getWhatsAppInboundMessages() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppInboundMessageList list = ms.whatsapp().inboundMessages()
.whatsappAccountId("whatsapp account id")
.from("48600000001")
.types(new String[]{"text", "image"})
.dateFrom(1790000000)
.dateTo(1790086400)
.page(1)
.limit(25)
.getInboundMessages();
for (WhatsAppInboundMessage inboundMessage : list.inboundMessages) {
System.out.println(inboundMessage.id);
System.out.println(inboundMessage.from);
System.out.println(inboundMessage.type);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Inbound Messages class
ms_whatsapp_inbound_messages = Mailersend::WhatsAppInboundMessages.new
# Add parameters
ms_whatsapp_inbound_messages.list(
whatsapp_account_id: 'your-whatsapp-account-id',
from: '48600000001',
type: %w[text image],
date_from: 1790000000,
date_to: 1790086400,
page: 1,
limit: 25
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data[].id` | `string` | ID of the inbound message. The same value is sent as `data.whatsapp_inbound_message_id` in the `whatsapp.inbound` [webhook](/api/v1/whatsapp/webhooks#inbound-messages). |
| `data[].whatsapp_account_id` | `string` | The MailerSend sender ID of the phone number that received the message. |
| `data[].from` | `string` | The phone number of the person who sent the message, or their BSUID. Use it as `to` in [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message) to reply. |
| `data[].to` | `string` | Your phone number that received the message. An empty string for a sender connected with a Meta virtual number. |
| `data[].type` | `string` | The kind of message. It determines the shape of `meta`. |
| `data[].received_at` | `string` | When WhatsApp received the message, in ISO 8601 format. |
| `data[].meta` | `object\|null` | The content of the message. Its shape depends on `type`. See [Message content](#message-content). |
| `data[].context` | `object` | Present only when the message is a reply. `context.message_id` is the WhatsApp ID of the message that was replied to. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "62f114f7165fe0d8db0288e2",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "48600000001",
"to": "15550001234",
"type": "text",
"received_at": "2026-10-14T12:41:19.000000Z",
"meta": {
"body": "Hello, I would like to check my order status."
},
"context": {
"message_id": "wamid.HBgLMzcwNjMzMjI3OTcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA"
}
},
{
"id": "62f114c1165fe0d8db0288d9",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "US.13491208655302741918",
"to": "15550001234",
"type": "image",
"received_at": "2026-10-14T12:38:03.000000Z",
"meta": {
"url": "https://app.mailersend.com/whatsapp/inbound-message-attachment/62f114c1165fe0d8db0288d9?account=3enl6x27wmrxrl2v&expires=1792022400&signature=...",
"status": "stored",
"mime_type": "image/jpeg",
"size": 102400,
"caption": "Here is the damaged item"
}
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/inbound-messages?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/inbound-messages?page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/inbound-messages",
"per_page": 25,
"to": 2
}
}
```
The top-level `meta` object holds the pagination details, while `data[].meta` holds the content of each message.
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when a parameter is invalid — including a `whatsapp_account_id` that does not belong to your account, a `from` that is longer than 255 characters or is not a phone number or BSUID, such as a WhatsApp username, an unknown value in `type[]`, a `date_from` or `date_to` without a time, a `date_to` that is not after `date_from`, or a `page` or `limit` out of range.
*See - [Validation errors](/general#validation-errors)*
## Get an inbound message [#get-an-inbound-message]
Get a single inbound message with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/inbound-messages/{inbound_message_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| -------------------- | -------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inbound_message_id` | `string` | yes | | The `id` of an inbound message, as returned by [`GET` /v1/whatsapp/inbound-messages](#get-a-list-of-inbound-messages) or sent as `data.id` in the `whatsapp.inbound` webhook. |
```bash
curl --request GET \
--url https://api.mailersend.com/v1/whatsapp/inbound-messages/62f114a3165fe0d8db0288d1 \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappInboundMessage = $mailersend->whatsappInboundMessage->find('inbound_message_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.whatsapp.inboundMessage.single("inbound_message_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, WhatsAppInboundMessagesBuilder
ms = MailerSendClient()
request = (WhatsAppInboundMessagesBuilder()
.whatsapp_inbound_message_id("inbound-message-id")
.build_get_request())
response = ms.whatsapp_inbound_messages.get_whatsapp_inbound_message(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()
_, _, err := ms.WhatsAppInboundMessage.Get(ctx, "inbound-message-id")
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.whatsapp.inboundmessages.WhatsAppInboundMessage;
public void getWhatsAppInboundMessage() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppInboundMessage inboundMessage = ms.whatsapp().inboundMessages().getInboundMessage("inbound message id");
System.out.println(inboundMessage.id);
System.out.println(inboundMessage.type);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Inbound Messages class
ms_whatsapp_inbound_messages = Mailersend::WhatsAppInboundMessages.new
# Add parameters
ms_whatsapp_inbound_messages.get(whatsapp_inbound_message_id: 'your-whatsapp-inbound-message-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
The response contains the same fields as an item of [the list](#get-a-list-of-inbound-messages).
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "62f114a3165fe0d8db0288d1",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "48600000001",
"to": "15550001234",
"type": "interactive",
"received_at": "2026-10-14T12:36:44.000000Z",
"meta": {
"reply_type": "list_reply",
"id": "delivery_today",
"title": "Deliver today",
"description": "Between 4 PM and 8 PM"
},
"context": {
"message_id": "wamid.HBgLMzcwNjMzMjI3OTcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA"
}
}
}
```
#### Error [#error-1]
```http
Response Code: 403 Forbidden
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 404 Not Found
```
Returned when the inbound message does not exist, belongs to another account, or is older than your plan's inbound retention period.
## Message content [#message-content]
The content of an inbound message is returned in `meta`, and its shape depends on the message `type`.
| `type` | `meta` |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `text` | `body` with the message text. |
| `image`, `audio`, `video`, `document`, `sticker` | The media file: `url`, `status`, `mime_type`, `size`, `caption` and more. See [Media](#media). |
| `location` | `latitude`, `longitude`, `name` and `address`. |
| `reaction` | `message_id` of the message that was reacted to, and `emoji`. |
| `button` | `text` and `payload` of the quick reply button that was tapped. |
| `interactive` | `reply_type`, `id`, `title` and `description`. `reply_type` is `button_reply` or `list_reply`. |
| `contacts` | `contacts`, an array of the shared contact cards as sent by WhatsApp. |
| `order`, `system`, `unknown`, `unsupported` | The object WhatsApp sent under the field named after the type, as received. `null` when WhatsApp sent none. |
Fields that WhatsApp did not send, such as the `name` of a shared location or the `caption` of an image, can be `null` or missing, so check that a field is set before you use it.
Some examples of `meta`:
```json
{
"type": "location",
"meta": {
"latitude": 52.2297,
"longitude": 21.0122,
"name": "Shop Brand Warehouse",
"address": "Prosta 20, 00-850 Warsaw"
}
}
```
```json
{
"type": "reaction",
"meta": {
"message_id": "wamid.HBgLMzcwNjMzMjI3OTcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA",
"emoji": "\ud83d\udc4d"
}
}
```
```json
{
"type": "button",
"meta": {
"text": "Track my order",
"payload": "track_order_12345"
}
}
```
### Media [#media]
For media messages, `meta` describes the file MailerSend downloaded from WhatsApp and links to it.
```json
{
"type": "document",
"meta": {
"url": "https://app.mailersend.com/whatsapp/inbound-message-attachment/62f114c1165fe0d8db0288d9?account=3enl6x27wmrxrl2v&expires=1792022400&signature=...",
"status": "stored",
"mime_type": "application/pdf",
"size": 48213,
"filename": "invoice-12345.pdf"
}
}
```
| Field | Type | Details |
| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `meta.url` | `string\|null` | A signed, time-limited URL to download the file. It expires together with the stored file. `null` when the file is not stored. |
| `meta.status` | `string` | `stored` when the file is available, `pending` while it is being downloaded, `failed` when it could not be downloaded, and `expired` when it is no longer kept. |
| `meta.mime_type` | `string` | The media type reported by WhatsApp. Present when known. |
| `meta.size` | `integer` | The file size in bytes. Present when known. |
| `meta.caption` | `string` | The caption, when the sender added one. |
| `meta.filename` | `string` | The original file name, when known. Usually present for documents. |
| `meta.animated` | `boolean` | Whether the sticker is animated. Present for stickers only. |
Inbound media is kept for 1 day, which is shorter than the inbound message itself. Once the file has expired, `meta.status` is `expired` and `meta.url` is `null`. Download the file as soon as you can if you need to keep it.
# Sending a WhatsApp message (/api/v1/whatsapp)
This endpoint allows you to send WhatsApp messages through the MailerSend WhatsApp API.
MailerSend sends WhatsApp messages through the WhatsApp Business Platform (Cloud API). Every business-initiated WhatsApp message must use a template that has been approved by Meta, so the API takes a template and the values for its variables instead of free-form message content.
## Before you start [#before-you-start]
| Requirement | Details |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| WhatsApp add-on | WhatsApp is a paid add-on. Enable it in your MailerSend account before sending. |
| Connected sender | Connect your WhatsApp Business Account (WABA) in **WhatsApp → Phone numbers**. The sender must stay connected for sending to work. |
| Approved template | Create a template and submit it to Meta. Only templates with the `approved` status can be sent. Approval takes from a few minutes up to 48 hours. |
| API token | Use a token with the `whatsapp_full` scope to send. The `whatsapp_read` scope lets a token view WhatsApp messages, items, activities, inbound messages, recipients and templates, but not send. See [token scopes](/api/v1/account/tokens#possible-scopes). |
Templates and senders are managed in your MailerSend account. You can look up your templates with [`GET` /v1/whatsapp/templates](/api/v1/whatsapp/templates#get-a-list-of-whatsapp-templates), but senders and templates cannot be created through the API.
## Send a WhatsApp message [#send-a-whatsapp-message]
This endpoint sends an asynchronous WhatsApp message to up to 10 recipients. It returns the ID of the created message in the response body and in the `X-Message-Id` header.
Send a WhatsApp message using this `POST` request:
```http
POST https://api.mailersend.com/v1/whatsapp/send
```
#### Request Body \[!toc] [#request-body-toc]
```json
{
"from": "15550001234",
"to": [
"+48600000001",
"+48600000002"
],
"template_id": "23zxk54v6gjy6v7m",
"personalization": [
{
"to": "+48600000001",
"data": {
"header": [
"Order #12345"
],
"body": [
"John",
"December 31, 2026"
],
"buttons": [
"orders/12345"
]
}
},
{
"to": "+48600000002",
"data": {
"header": [
"Order #12346"
],
"body": [
"Jane",
"January 4, 2027"
],
"buttons": [
"orders/12346"
]
}
}
]
}
```
```bash
curl --request POST \
--url https://api.mailersend.com/v1/whatsapp/send \
--header 'Authorization: Bearer API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
"from": "15550001234",
"to": ["+48600000001"],
"template_id": "23zxk54v6gjy6v7m",
"personalization": [
{
"to": "+48600000001",
"data": {
"body": ["John", "December 31, 2026"]
}
}
]
}'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappParams;
use MailerSend\Helpers\Builder\WhatsappPersonalization;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappParams = (new WhatsappParams())
->setFrom('15550001234')
->setTo(['+48600000001'])
->addRecipient('+48600000002')
->setTemplateId('23zxk54v6gjy6v7m')
->setPersonalization([
(new WhatsappPersonalization('+48600000001'))
->setHeader(['Order #12345'])
->setBody(['John', 'December 31, 2026'])
->setButtons(['orders/12345']),
(new WhatsappPersonalization('+48600000002'))
->setHeader(['Order #12346'])
->setBody(['Jane', 'January 4, 2027'])
->setButtons(['orders/12346']),
]);
$whatsapp = $mailersend->whatsapp->send($whatsappParams);
```
[More examples](https://github.com/mailersend/mailersend-php)
```javascript
import { MailerSend, WhatsAppParams, WhatsAppPersonalization } from "mailersend";
const mailersend = new MailerSend({
apiKey: process.env.API_KEY,
});
const personalization = [
new WhatsAppPersonalization("+48600000001")
.setHeader(["Order #12345"])
.setBody(["John", "December 31, 2026"])
.setButtons(["orders/12345"]),
new WhatsAppPersonalization("+48600000002")
.setHeader(["Order #12346"])
.setBody(["Jane", "January 4, 2027"])
.setButtons(["orders/12346"]),
];
const whatsappParams = new WhatsAppParams()
.setFrom("15550001234")
.setTo(["+48600000001", "+48600000002"])
.setTemplateId("23zxk54v6gjy6v7m")
.setPersonalization(personalization);
await mailersend.whatsapp.send(whatsappParams);
```
[More examples](https://github.com/mailersend/mailersend-nodejs)
```python
from mailersend import MailerSendClient, WhatsAppBuilder
from mailersend.models.whatsapp import (
WhatsAppPersonalization,
WhatsAppPersonalizationData,
)
ms = MailerSendClient()
request = (
WhatsAppBuilder()
.from_number("15550001234")
.to(["+48600000001", "+48600000002"])
.template_id("23zxk54v6gjy6v7m")
.add_personalization(
WhatsAppPersonalization(
to="+48600000001",
data=WhatsAppPersonalizationData(
header=["Order #12345"],
body=["John", "December 31, 2026"],
buttons=["orders/12345"],
),
)
)
.add_personalization(
WhatsAppPersonalization(
to="+48600000002",
data=WhatsAppPersonalizationData(
header=["Order #12346"],
body=["Jane", "January 4, 2027"],
buttons=["orders/12346"],
),
)
)
.build()
)
response = ms.whatsapp.send(request)
```
[More examples](https://github.com/mailersend/mailersend-python)
```go
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/mailersend/mailersend-go"
)
var APIKey = "Api Key Here"
func main() {
ms := mailersend.NewMailersend(APIKey)
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
message := ms.WhatsApp.NewMessage()
message.SetFrom("15550001234")
message.SetTo([]string{"48600000001", "48600000002"})
message.SetTemplateID("23zxk54v6gjy6v7m")
personalization := []mailersend.WhatsAppPersonalization{
{
To: "48600000001",
Data: mailersend.WhatsAppPersonalizationData{
Header: []string{"Order #12345"},
Body: []string{"John", "December 31, 2026"},
Buttons: []string{"orders/12345"},
},
},
{
To: "48600000002",
Data: mailersend.WhatsAppPersonalizationData{
Header: []string{"Order #12346"},
Body: []string{"Jane", "January 4, 2027"},
Buttons: []string{"orders/12346"},
},
},
}
message.SetPersonalization(personalization)
res, err := ms.WhatsApp.Send(ctx, message)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Header.Get("X-Message-Id"))
}
```
[More examples](https://github.com/mailersend/mailersend-go)
```java
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.whatsapp.WhatsAppPersonalization;
public void sendWhatsApp() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppPersonalization p1 = new WhatsAppPersonalization("+48600000001")
.setHeader(new String[]{"Order #12345"})
.setBody(new String[]{"John", "December 31, 2026"})
.setButtons(new String[]{"orders/12345"});
WhatsAppPersonalization p2 = new WhatsAppPersonalization("+48600000002")
.setHeader(new String[]{"Order #12346"})
.setBody(new String[]{"Jane", "January 4, 2027"})
.setButtons(new String[]{"orders/12346"});
String messageId = ms.whatsapp().builder()
.from("15550001234")
.addRecipient("+48600000001")
.addRecipient("+48600000002")
.templateId("23zxk54v6gjy6v7m")
.addPersonalization(p1)
.addPersonalization(p2)
.send();
System.out.println(messageId);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Initialize the WhatsApp class
ms_whatsapp = Mailersend::WhatsApp.new
# Add parameters
ms_whatsapp.add_from('15550001234')
ms_whatsapp.add_to('+48600000001')
ms_whatsapp.add_to('+48600000002')
ms_whatsapp.add_template_id('23zxk54v6gjy6v7m')
ms_whatsapp.add_personalization({
to: '+48600000001',
data: {
header: ['Order #12345'],
body: ['John', 'December 31, 2026'],
buttons: ['orders/12345']
}
})
ms_whatsapp.add_personalization({
to: '+48600000002',
data: {
header: ['Order #12346'],
body: ['Jane', 'January 4, 2027'],
buttons: ['orders/12346']
}
})
# Send the message
ms_whatsapp.send
```
[More examples](https://github.com/mailersend/mailersend-ruby)
#### Request parameters \[!toc] [#request-parameters-toc]
*JSON parameters are provided in dot notation*
| JSON parameter | Type | Required | Limitations | Details |
| -------------------------------- | ---------- | -------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from` | `string` | yes | | The sender to send from. Must be one of your connected WhatsApp senders. See [Sender identifiers](#sender-identifiers). |
| `to` | `string[]` | yes | `min:1`, `max:10` | The recipients of the message. Each recipient must be unique within the request. |
| `to.*` | `string` | yes | | A phone number in E.164 format, or a BSUID taken from an inbound message. WhatsApp usernames cannot be used as recipients. See [Recipients](#recipients). |
| `template_id` | `string` | yes | | The ID of an approved template that belongs to the sender in `from`. You can find it in **WhatsApp → Templates** or with [`GET` /v1/whatsapp/templates](/api/v1/whatsapp/templates#get-a-list-of-whatsapp-templates). |
| `personalization` | `object[]` | no | `max:10` | The values for the template's variables, per recipient. See [Personalization](#personalization). |
| `personalization.*.to` | `string` | yes | | The recipient the values apply to. Must be one of the values in `to`. |
| `personalization.*.data` | `object` | yes | | Object containing the `header`, `body` and `buttons` sections. |
| `personalization.*.data.header` | `string[]` | no | Max `60` characters per value | Values for the variables in the template header, in order. |
| `personalization.*.data.body` | `string[]` | no | Max `1024` characters per value | Values for the variables in the template body, in order. |
| `personalization.*.data.buttons` | `string[]` | no | Max `2000` characters per value | Values for the variables in the template's URL buttons, in order. |
### Sender identifiers [#sender-identifiers]
The `from` field accepts two forms of identifier. Both are scoped to your account and only resolve to a sender that is currently connected. You can find both in **WhatsApp → Phone numbers**.
| Form | Example | Details |
| -------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| Phone number | `15550001234` | The sender's phone number in E.164 format. |
| MailerSend sender ID | `3enl6x27wmrxrl2v` | Also returned as `data.sender.id` in every [webhook](/api/v1/whatsapp/webhooks) payload. |
A sender connected with a Meta virtual number has no phone number, so it can only be addressed by its MailerSend sender ID.
The MailerSend sender ID is stable across disconnecting and reconnecting a sender, which is not true of the phone number. Use it if you need a durable reference in your integration.
### Recipients [#recipients]
Recipients can be addressed in two ways:
* **A phone number** in E.164 format, for example `+48600000001`. Spaces, dashes, brackets, dots and the leading `+` are removed before the number is validated, so `+48 600 000 001` and `48600000001` are the same recipient.
* **A BSUID** (Business-Scoped User ID), for example `US.13491208655302741918`. Meta provides it in the payload of an inbound message, and it lets you reply to a user who contacted you without their phone number.
WhatsApp usernames cannot be used as recipients. Meta does not allow looking up a username, so use the recipient's phone number or the BSUID from their inbound message instead.
### Personalization [#personalization]
Template variables are filled per recipient. Each entry in `personalization` targets one recipient from `to` and carries the values for the template's `header`, `body` and `buttons` sections.
Values are positional: the first value in the array replaces `{{1}}`, the second replaces `{{2}}`, and so on. Only variables in URL buttons are personalized, so the `buttons` array holds the URL parameters in the order the buttons appear in the template.
```json
{
"to": "+48600000001",
"data": {
"header": ["Order #12345"],
"body": ["John", "December 31, 2026"],
"buttons": ["orders/12345"]
}
}
```
The number of values in each section must match the number of variables the template has in that section, for every recipient in `to`. A mismatch fails the whole request with a `422` response instead of failing per recipient after the message was queued:
```json
{
"message": "The given data was invalid.",
"errors": {
"personalization.0.data.body": [
"The template expects 2 body variable(s) for 48600000001, 1 given."
]
}
}
```
Authentication templates always expect exactly one `body` variable — the verification code. It is copied into the template's copy code button automatically, so leave `buttons` empty for them.
Objects with named keys, such as `"body": {"name": "John", "date": "December 31, 2026"}`, are also accepted. The values are used in the order they appear in the object, so a positional array is the safer choice.
### Sandbox [#sandbox]
The sandbox lets you test your integration without a connected WABA or an approved template. Activate it in **WhatsApp → Sandbox**, where you connect your own phone number to the MailerSend sandbox number and get the sandbox templates.
To send a sandbox message, use the sandbox number as the `from` value and one of the sandbox templates as the `template_id`. Sandbox sends are limited to 1 recipient per request and 20 messages per day, the sandbox connection expires after 1 hour, and sandbox messages are not counted against your monthly WhatsApp message cap.
### Responses [#responses]
#### Sending queued [#sending-queued]
```http
Response Code: 202 Accepted
Response Headers:
content-type: application/json
X-Message-Id: 67f91abd69f79df391e9d78d
```
```json
{
"data": {
"id": "67f91abd69f79df391e9d78d",
"created_at": "2026-08-31 07:24:20"
}
}
```
The message is accepted and queued. Each recipient is processed individually, and the delivery result for each one is reported through [webhooks](/api/v1/whatsapp/webhooks).
#### Missing permissions [#missing-permissions]
```http
Response Code: 403 Forbidden
Response Headers:
content-type: application/json
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_full` scope. A token with only the `whatsapp_read` scope cannot send messages.
#### No connected sender [#no-connected-sender]
```http
Response Code: 403 Forbidden
Response Headers:
content-type: application/json
```
```json
{
"message": "This action is unauthorized."
}
```
Your account has no connected WhatsApp sender, or the account is suspended.
#### Validation error [#validation-error]
```http
Response Code: 422 Unprocessable Entity
Response Headers:
content-type: application/json
```
```json
{
"message": "The given data was invalid.",
"errors": {
"from": [
"The from does not match any of your connected WhatsApp senders."
],
"template_id": [
"The selected template cannot be used for sending because it is in review. Only approved templates can be sent."
]
}
}
```
*See - [Validation errors](/general#validation-errors)*
#### Message rejected [#message-rejected]
```http
Response Code: 422 Unprocessable Entity
Response Headers:
content-type: application/json
```
```json
{
"error": "Failed to send WhatsApp message",
"message": "We could not accept this WhatsApp message. Check that the sender is still connected and try again."
}
```
The request was valid but the message could not be accepted, most commonly because the sender was disconnected between your request and the send.
### Common validation errors [#common-validation-errors]
| Error | Cause |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `The from does not match any of your connected WhatsApp senders.` | The sender identifier is unknown, or the sender has been disconnected. |
| `The to.0 must be a valid phone number or BSUID.` | A recipient is not a valid E.164 phone number or BSUID. |
| `The to.0 cannot be a WhatsApp username.` | Usernames cannot be used as recipients. Use a phone number or a BSUID. |
| `Maximum 10 recipients allowed.` | Split the request into batches of up to 10 recipients. |
| `Each recipient can only be listed once per request.` | The same recipient appears more than once in `to`. |
| `The selected template does not exist.` | The template ID is unknown or the template was deleted. |
| `The selected template cannot be used for sending because it is .` | Only approved templates can be sent. |
| `The selected template belongs to a different WhatsApp sender.` | Use a template that was created for the sender in `from`. |
| `WhatsApp sending has been paused. You have reached your monthly message cap.` | The account has reached the message cap of its WhatsApp add-on for the current billing period. |
## Tracking delivery [#tracking-delivery]
WhatsApp messages are sent asynchronously, so the `202` response only means the message was accepted. To learn what happened to each recipient's message, create a webhook for your sender and listen for the `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read` and `whatsapp.failed` events. Inbound messages from your recipients are delivered as `whatsapp.inbound` events.
Read more about [WhatsApp webhooks](/api/v1/whatsapp/webhooks).
You can also retrieve the same information with the API:
* [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message) returns a message with one item per recipient, including its current status and error. Use the `id` from the `202` response. Items are created asynchronously, so `items` can be empty right after sending.
* [`GET` /v1/whatsapp/items/\{item\_id}](/api/v1/whatsapp/items#get-a-whatsapp-item) returns the delivery to one recipient with every status it moved through.
* [`GET` /v1/whatsapp/activities](/api/v1/whatsapp/activities#get-a-list-of-whatsapp-activities) lists the status events of your messages.
* [`GET` /v1/whatsapp/inbound-messages](/api/v1/whatsapp/inbound-messages#get-a-list-of-inbound-messages) lists the messages your recipients sent to your phone numbers.
* [`GET` /v1/whatsapp/recipients](/api/v1/whatsapp/recipients#get-a-list-of-whatsapp-recipients) lists your recipients and their status.
Sent WhatsApp messages, activity and webhook logs are kept for 7 days. Inbound messages are kept for the inbound retention period of your plan: 7, 14 or 30 days. Store anything you need for longer in your own system, for example by consuming webhook events.
# Items (/api/v1/whatsapp/items)
An item is the delivery of a [WhatsApp message](/api/v1/whatsapp/messages) to one recipient. A message sent to 3 recipients has 3 items, and each item moves through its statuses independently. See [WhatsApp status list](/general#whatsapp-status-list).
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
Items are kept for 7 days, the same as the message they belong to. An item older than that is no longer listed, and requesting it returns `404`.
## Get a list of WhatsApp items [#get-a-list-of-whatsapp-items]
Get a list of the deliveries of your WhatsApp messages with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/items
```
Items are returned newest first.
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient` | `string` | no | | The recipient's phone number in international format, WhatsApp username or BSUID. See [Filtering](#filtering). |
| `whatsapp_message_id` | `string` | no | | The ID of the message the items belong to. |
| `status[]` | `string[]` | no | Possible values: `queued`, `sent`, `delivered`, `read`, `failed` | Array only. Multiple values are combined with `OR`. |
| `whatsapp_account_id` | `string` | no | Must be one of your WhatsApp senders. | The MailerSend sender ID the messages were sent from. A deleted sender is accepted. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `from` | `string` | no | Max: `32` characters | The sender's phone number in international format. |
| `template_id` | `string` | no | | The ID of the template that was sent. |
| `date_from` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be lower than `date_to`. No fractional seconds: `2026-10-14T00:00:00.000Z` is rejected. | Unix timestamp: `1791936000`, ISO 8601 datetime: `2026-10-14T00:00:00Z` or datetime: `2026-10-14 00:00:00`. Exclusive. |
| `date_to` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be higher than `date_from`. No fractional seconds: `2026-10-15T00:00:00.000Z` is rejected. | Unix timestamp: `1792022400`, ISO 8601 datetime: `2026-10-15T00:00:00Z` or datetime: `2026-10-15 00:00:00`. Exclusive. |
| `page` | `int` | no | Min: `1`, Max: `100` | To reach older items beyond page `100`, narrow `date_from` and `date_to`. |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
#### Filtering \[!toc] [#filtering-toc]
`date_from` and `date_to` are exclusive: only items created strictly after `date_from` and strictly before `date_to` are returned. Both accept a Unix timestamp, an ISO 8601 datetime with `Z` or an offset such as `2026-10-14T00:00:00+02:00`, or a datetime in `Y-m-d H:i:s` format. A date without a time, such as `2026-10-14`, returns a `422` validation error.
`recipient` accepts a phone number in international format, a WhatsApp username or a BSUID. `from` accepts a phone number in international format. In phone numbers, spaces, dashes and the leading `+` are ignored, so `+48 600-000-001` and `48600000001` match the same recipient.
`status[]` must be sent as an array, for example `?status[]=delivered&status[]=read`.
An example request that returns the failed deliveries to one recipient over one day:
```http
GET https://api.mailersend.com/v1/whatsapp/items?recipient=48600000002&status[]=failed&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z
```
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/items?recipient=48600000002&status[]=failed&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z&limit=25' \
--globoff \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappItemParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappItemParams = (new WhatsappItemParams())
->setRecipient('48600000002')
->setStatus(['failed'])
->setDateFrom('2026-10-14T00:00:00Z')
->setDateTo('2026-10-15T00:00:00Z')
->setPage(1)
->setLimit(25);
$whatsappItems = $mailersend->whatsappItem->getAll($whatsappItemParams);
```
[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.whatsapp.item.list({
recipient: "48600000002",
status: ["failed"],
date_from: 1791936000,
date_to: 1792022400,
limit: 25,
page: 1,
})
.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, WhatsAppItemsBuilder
from mailersend.models.whatsapp_items import WhatsAppItemStatus
ms = MailerSendClient()
request = (WhatsAppItemsBuilder()
.recipient("48600000002")
.status([WhatsAppItemStatus.FAILED])
.date_from("2026-10-14T00:00:00Z")
.date_to("2026-10-15T00:00:00Z")
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_items.list_whatsapp_items(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.ListWhatsAppItemOptions{
Recipient: "48600000002",
Status: []string{"failed"},
DateFrom: 1791936000,
DateTo: 1792022400,
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppItem.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.whatsapp.items.WhatsAppItem;
import com.mailersend.sdk.whatsapp.items.WhatsAppItemList;
public void getWhatsAppItems() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppItemList list = ms.whatsapp().items()
.recipient("48600000002")
.addStatusFilter("failed")
.dateFrom(1791936000)
.dateTo(1792022400)
.page(1)
.limit(25)
.getItems();
for (WhatsAppItem item : list.items) {
System.out.println(item.id);
System.out.println(item.status);
System.out.println(item.errorCode);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Items class
ms_whatsapp_items = Mailersend::WhatsAppItems.new
# Add parameters
ms_whatsapp_items.list(
recipient: '48600000002',
status: %w[failed],
date_from: 1791936000,
date_to: 1792022400,
page: 1,
limit: 25
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data[].id` | `string` | ID of the item. The same value is sent as `data.whatsapp_item_id` in [webhooks](/api/v1/whatsapp/webhooks). |
| `data[].whatsapp_message_id` | `string` | ID of the message the item belongs to. Pass it to [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message). |
| `data[].whatsapp_account_id` | `string\|null` | The MailerSend sender ID of the phone number the message was sent from. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `data[].from` | `string\|null` | The sender's phone number, or its WhatsApp username when the message was sent from the username or the sender has no phone number, such as one connected with a Meta virtual number. `null` when the sender has neither. |
| `data[].to` | `string` | The recipient's phone number or BSUID. |
| `data[].status` | `string` | The current status: `queued`, `sent`, `delivered`, `read` or `failed`. See [WhatsApp status list](/general#whatsapp-status-list). |
| `data[].template_id` | `string\|null` | The ID of the template that was sent. |
| `data[].template_name` | `string\|null` | The name of the template that was sent. `null` when the delivery failed before the template was loaded. |
| `data[].error_code` | `int\|null` | The WhatsApp Cloud API error code when the delivery failed, otherwise `null`. See Meta's [error code reference](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes). |
| `data[].error_message` | `string\|null` | The error message returned by WhatsApp when the delivery failed, otherwise `null`. |
| `data[].created_at` | `string` | When the item was created, in ISO 8601 format. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "67f91abe2202f3705540234b",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000002",
"status": "failed",
"template_id": "23zxk54v6gjy6v7m",
"template_name": "Order confirmation",
"error_code": 131026,
"error_message": "Message undeliverable",
"created_at": "2026-10-14T12:25:33.000000Z"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/items?recipient=48600000002&status%5B0%5D=failed&date_from=2026-10-14T00%3A00%3A00Z&date_to=2026-10-15T00%3A00%3A00Z&limit=25&page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/items?recipient=48600000002&status%5B0%5D=failed&date_from=2026-10-14T00%3A00%3A00Z&date_to=2026-10-15T00%3A00%3A00Z&limit=25&page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/items",
"per_page": 25,
"to": 1
}
}
```
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when a parameter is invalid — including a `whatsapp_account_id` that does not belong to your account, an unknown value in `status[]`, a `from` that is not a phone number or is longer than 32 characters, a `date_from` or `date_to` without a time, a `date_to` that is not after `date_from`, or a `page` or `limit` out of range.
*See - [Validation errors](/general#validation-errors)*
## Get a WhatsApp item [#get-a-whatsapp-item]
Get a single item, together with its recipient and every status it moved through, with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/items/{item_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item_id` | `string` | yes | | The `id` of an item, as returned by [`GET` /v1/whatsapp/items](#get-a-list-of-whatsapp-items) or [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message), or sent as `data.whatsapp_item_id` in [webhooks](/api/v1/whatsapp/webhooks). |
```bash
curl --request GET \
--url https://api.mailersend.com/v1/whatsapp/items/67f91abe2202f3705540234a \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappItem = $mailersend->whatsappItem->find('item_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.whatsapp.item.single("item_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, WhatsAppItemsBuilder
ms = MailerSendClient()
request = (WhatsAppItemsBuilder()
.whatsapp_item_id("item-id")
.build_get_request())
response = ms.whatsapp_items.get_whatsapp_item(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()
_, _, err := ms.WhatsAppItem.Get(ctx, "item-id")
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.whatsapp.items.WhatsAppItem;
public void getWhatsAppItem() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppItem item = ms.whatsapp().items().getItem("item id");
System.out.println(item.id);
System.out.println(item.status);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Items class
ms_whatsapp_items = Mailersend::WhatsAppItems.new
# Add parameters
ms_whatsapp_items.get(whatsapp_item_id: 'your-whatsapp-item-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
The response contains the same fields as an item of [the list](#get-a-list-of-whatsapp-items), plus `recipient` and `activity`.
| Response key | Type | Details |
| ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data.recipient` | `object` | The recipient the message was delivered to. See [Recipients](/api/v1/whatsapp/recipients). |
| `data.recipient.id` | `string` | ID of the recipient. Pass it to [`GET` /v1/whatsapp/recipients/\{recipient\_id}](/api/v1/whatsapp/recipients#get-a-whatsapp-recipient). |
| `data.recipient.phone_number` | `string\|null` | The recipient's phone number, when known. |
| `data.recipient.username` | `string\|null` | The recipient's WhatsApp username, when known. |
| `data.recipient.status` | `string` | `active`, `invalid`, `suppressed` or `blocked`. |
| `data.recipient.created_at` | `string` | When the recipient was created, in ISO 8601 format. |
| `data.activity` | `object[]` | Every status the item moved through, ordered by status (`queued`, `sent`, `delivered`, `read`, `failed`) and then by `created_at`, so statuses recorded within the same second still come out in that order. |
| `data.activity.*.type` | `string` | The status that was recorded: `queued`, `sent`, `delivered`, `read` or `failed`. |
| `data.activity.*.created_at` | `string` | When the status was recorded, in ISO 8601 format. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "67f91abe2202f3705540234a",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000001",
"status": "read",
"template_id": "23zxk54v6gjy6v7m",
"template_name": "Order confirmation",
"error_code": null,
"error_message": null,
"created_at": "2026-10-14T12:25:33.000000Z",
"recipient": {
"id": "67f91abe2202f37055402301",
"phone_number": "48600000001",
"username": null,
"status": "active",
"created_at": "2026-09-02T08:14:51.000000Z"
},
"activity": [
{
"type": "queued",
"created_at": "2026-10-14T12:25:33.000000Z"
},
{
"type": "sent",
"created_at": "2026-10-14T12:25:34.000000Z"
},
{
"type": "delivered",
"created_at": "2026-10-14T12:25:36.000000Z"
},
{
"type": "read",
"created_at": "2026-10-14T12:31:02.000000Z"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 403 Forbidden
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 404 Not Found
```
Returned when the item does not exist, belongs to another account, or is older than the 7-day retention period.
# Messages (/api/v1/whatsapp/messages)
A WhatsApp message is the resource created by a single [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message) request. One message can have up to 10 recipients, and the delivery to each recipient is tracked separately as an [item](/api/v1/whatsapp/items).
* **Messages** return one row per `POST` /v1/whatsapp/send request.
* **[Items](/api/v1/whatsapp/items)** return one row per recipient of a message, with its current status.
* **[Activities](/api/v1/whatsapp/activities)** return one row per status event, so a single item appears once as `queued`, once as `sent`, once as `delivered`, and so on.
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
Sent WhatsApp messages are kept for 7 days. A message older than that is no longer listed, and requesting it returns `404`.
## Get a list of WhatsApp messages [#get-a-list-of-whatsapp-messages]
Get a list of the WhatsApp messages sent from your account with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/messages
```
Messages are returned newest first. The list does not include `items`; use [`GET` /v1/whatsapp/messages/\{message\_id}](#get-a-whatsapp-message) or [`GET` /v1/whatsapp/items](/api/v1/whatsapp/items#get-a-list-of-whatsapp-items) for the delivery to each recipient.
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whatsapp_account_id` | `string` | no | Must be one of your WhatsApp senders. | The MailerSend sender ID the messages were sent from. A deleted sender is accepted. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `from` | `string` | no | Max: `32` characters | The sender's phone number in international format. See [Filtering](#filtering). |
| `template_id` | `string` | no | | The ID of the template that was sent. |
| `date_from` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be lower than `date_to`. No fractional seconds: `2026-10-14T00:00:00.000Z` is rejected. | Unix timestamp: `1791936000`, ISO 8601 datetime: `2026-10-14T00:00:00Z` or datetime: `2026-10-14 00:00:00`. Exclusive. |
| `date_to` | `int\|string` | no | Timestamp is assumed to be `UTC`. Must be higher than `date_from`. No fractional seconds: `2026-10-15T00:00:00.000Z` is rejected. | Unix timestamp: `1792022400`, ISO 8601 datetime: `2026-10-15T00:00:00Z` or datetime: `2026-10-15 00:00:00`. Exclusive. |
| `page` | `int` | no | Min: `1`, Max: `100` | To reach older messages beyond page `100`, narrow `date_from` and `date_to`. |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
#### Filtering \[!toc] [#filtering-toc]
`date_from` and `date_to` are exclusive: only messages created strictly after `date_from` and strictly before `date_to` are returned. Both accept a Unix timestamp, an ISO 8601 datetime with `Z` or an offset such as `2026-10-14T00:00:00+02:00`, or a datetime in `Y-m-d H:i:s` format. A date without a time, such as `2026-10-14`, returns a `422` validation error.
`from` accepts a phone number in international format. Spaces, dashes and the leading `+` are ignored, so `+1 555-000-1234` and `15550001234` match the same sender.
An example request that returns the messages one sender sent with one template over one day:
```http
GET https://api.mailersend.com/v1/whatsapp/messages?whatsapp_account_id=3enl6x27wmrxrl2v&template_id=23zxk54v6gjy6v7m&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z&limit=50
```
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/messages?whatsapp_account_id=3enl6x27wmrxrl2v&template_id=23zxk54v6gjy6v7m&date_from=2026-10-14T00:00:00Z&date_to=2026-10-15T00:00:00Z&limit=25' \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappMessageParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappMessageParams = (new WhatsappMessageParams())
->setWhatsappAccountId('whatsapp_account_id')
->setFrom('15550001234')
->setTemplateId('template_id')
->setDateFrom('2026-10-14T00:00:00Z')
->setDateTo('2026-10-15T00:00:00Z')
->setPage(1)
->setLimit(25);
$whatsappMessages = $mailersend->whatsappMessage->getAll($whatsappMessageParams);
```
[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.whatsapp.message.list({
whatsapp_account_id: "whatsapp_account_id",
from: "15550001234",
template_id: "template_id",
date_from: 1791936000,
date_to: 1792022400,
limit: 25,
page: 1,
})
.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, WhatsAppMessagesBuilder
ms = MailerSendClient()
request = (WhatsAppMessagesBuilder()
.whatsapp_account_id("whatsapp-account-id")
.from_number("15550001234")
.template_id("template-id")
.date_from("2026-10-14T00:00:00Z")
.date_to("2026-10-15T00:00:00Z")
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_messages.list_whatsapp_messages(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.ListWhatsAppMessageOptions{
WhatsAppAccountID: "whatsapp-account-id",
From: "15550001234",
TemplateID: "template-id",
DateFrom: 1791936000,
DateTo: 1792022400,
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppMessage.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.whatsapp.messages.WhatsAppMessage;
import com.mailersend.sdk.whatsapp.messages.WhatsAppMessageList;
public void getWhatsAppMessages() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppMessageList list = ms.whatsapp().messages()
.whatsappAccountId("whatsapp account id")
.from("15550001234")
.templateId("template id")
.dateFrom(1791936000)
.dateTo(1792022400)
.page(1)
.limit(25)
.getMessages();
for (WhatsAppMessage message : list.messages) {
System.out.println(message.id);
System.out.println(message.templateId);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Messages class
ms_whatsapp_messages = Mailersend::WhatsAppMessages.new
# Add parameters
ms_whatsapp_messages.list(
whatsapp_account_id: 'your-whatsapp-account-id',
from: '15550001234',
template_id: 'your-template-id',
date_from: 1791936000,
date_to: 1792022400,
page: 1,
limit: 25
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data[].id` | `string` | ID of the message. The same value is returned by [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message) in the response body and the `X-Message-Id` header, and sent as `data.whatsapp_message_id` in [webhooks](/api/v1/whatsapp/webhooks). |
| `data[].from` | `string\|null` | The sender's phone number, or its WhatsApp username when the message was sent from the username or the sender has no phone number, such as one connected with a Meta virtual number. `null` when the sender has neither. |
| `data[].to` | `string[]` | The recipients of the message. |
| `data[].whatsapp_account_id` | `string\|null` | The MailerSend sender ID of the phone number the message was sent from. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `data[].template_id` | `string\|null` | The ID of the template that was sent. |
| `data[].created_at` | `string` | When the message was created, in ISO 8601 format. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "67f91abd69f79df391e9d78d",
"from": "15550001234",
"to": [
"48600000001",
"48600000002"
],
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"template_id": "23zxk54v6gjy6v7m",
"created_at": "2026-10-14T12:25:33.000000Z"
},
{
"id": "67f91a0c69f79df391e9d6a1",
"from": null,
"to": [
"US.13491208655302741918"
],
"whatsapp_account_id": "p6nq4jyzkyv5x3zl",
"template_id": "6v7m23zxk54vgjy2",
"created_at": "2026-10-14T12:21:16.000000Z"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/messages?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/messages?page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/messages",
"per_page": 25,
"to": 2
}
}
```
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when a parameter is invalid — including a `whatsapp_account_id` that does not belong to your account, a `from` that is not a phone number or is longer than 32 characters, a `date_from` or `date_to` without a time, a `date_to` that is not after `date_from`, or a `page` or `limit` out of range.
*See - [Validation errors](/general#validation-errors)*
## Get a WhatsApp message [#get-a-whatsapp-message]
Get a single WhatsApp message, together with the delivery to each of its recipients, with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/messages/{message_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message_id` | `string` | yes | | The `id` of a message, as returned by [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message) in the response body and the `X-Message-Id` header, or by [`GET` /v1/whatsapp/messages](#get-a-list-of-whatsapp-messages). |
```bash
curl --request GET \
--url https://api.mailersend.com/v1/whatsapp/messages/67f91abd69f79df391e9d78d \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappMessage = $mailersend->whatsappMessage->find('message_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.whatsapp.message.single("message_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, WhatsAppMessagesBuilder
ms = MailerSendClient()
request = (WhatsAppMessagesBuilder()
.whatsapp_message_id("message-id")
.build_get_request())
response = ms.whatsapp_messages.get_whatsapp_message(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()
_, _, err := ms.WhatsAppMessage.Get(ctx, "message-id")
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.whatsapp.messages.WhatsAppMessage;
public void getWhatsAppMessage() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppMessage message = ms.whatsapp().messages().getMessage("message id");
System.out.println(message.id);
System.out.println(message.templateId);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Messages class
ms_whatsapp_messages = Mailersend::WhatsAppMessages.new
# Add parameters
ms_whatsapp_messages.get(whatsapp_message_id: 'your-whatsapp-message-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
The response contains the same fields as an item of [the list](#get-a-list-of-whatsapp-messages), plus `items`.
| Response key | Type | Details |
| ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data.items` | `object[]` | One item per recipient of the message. Items are created asynchronously, so `items` can be empty right after the message is sent. |
| `data.items.*.id` | `string` | ID of the item. The same value is sent as `data.whatsapp_item_id` in [webhooks](/api/v1/whatsapp/webhooks). |
| `data.items.*.whatsapp_message_id` | `string` | ID of the message the item belongs to. |
| `data.items.*.whatsapp_account_id` | `string\|null` | The MailerSend sender ID of the phone number the message was sent from. |
| `data.items.*.from` | `string\|null` | The sender's phone number, or its WhatsApp username when the message was sent from the username or the sender has no phone number, such as one connected with a Meta virtual number. `null` when the sender has neither. |
| `data.items.*.to` | `string` | The recipient's phone number or BSUID. |
| `data.items.*.status` | `string` | The current status: `queued`, `sent`, `delivered`, `read` or `failed`. See [WhatsApp status list](/general#whatsapp-status-list). |
| `data.items.*.template_id` | `string\|null` | The ID of the template that was sent. |
| `data.items.*.template_name` | `string\|null` | The name of the template that was sent. `null` when the delivery failed before the template was loaded. |
| `data.items.*.error_code` | `int\|null` | The WhatsApp Cloud API error code when the delivery failed, otherwise `null`. See Meta's [error code reference](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes). |
| `data.items.*.error_message` | `string\|null` | The error message returned by WhatsApp when the delivery failed, otherwise `null`. |
| `data.items.*.created_at` | `string` | When the item was created, in ISO 8601 format. |
To get the status timeline of one recipient, use [`GET` /v1/whatsapp/items/\{item\_id}](/api/v1/whatsapp/items#get-a-whatsapp-item) or [`GET` /v1/whatsapp/activities](/api/v1/whatsapp/activities#get-a-list-of-whatsapp-activities).
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "67f91abd69f79df391e9d78d",
"from": "15550001234",
"to": [
"48600000001",
"48600000002"
],
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"template_id": "23zxk54v6gjy6v7m",
"created_at": "2026-10-14T12:25:33.000000Z",
"items": [
{
"id": "67f91abe2202f3705540234a",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000001",
"status": "read",
"template_id": "23zxk54v6gjy6v7m",
"template_name": "Order confirmation",
"error_code": null,
"error_message": null,
"created_at": "2026-10-14T12:25:33.000000Z"
},
{
"id": "67f91abe2202f3705540234b",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000002",
"status": "failed",
"template_id": "23zxk54v6gjy6v7m",
"template_name": "Order confirmation",
"error_code": 131026,
"error_message": "Message undeliverable",
"created_at": "2026-10-14T12:25:33.000000Z"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 403 Forbidden
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 404 Not Found
```
Returned when the message does not exist, belongs to another account, or is older than the 7-day retention period.
# Recipients (/api/v1/whatsapp/recipients)
Get information about the people you have sent WhatsApp messages to.
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
## Get a list of WhatsApp recipients [#get-a-list-of-whatsapp-recipients]
Get a list of WhatsApp recipients with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/recipients
```
Recipients are returned newest first.
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------- | -------- | -------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `string` | no | `active`, `invalid`, `suppressed`, `blocked` | |
| `phone_number` | `string` | no | Max: `32` characters | The recipient's phone number in international format. Spaces, dashes and the leading `+` are ignored, so `+48 600-000-001` and `48600000001` match the same recipient. |
| `page` | `int` | no | Min: `1`, Max: `100` | |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/recipients?status=active&phone_number=48600000001&limit=25' \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappRecipientParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappRecipientParams = (new WhatsappRecipientParams())
->setStatus('active')
->setPhoneNumber('48600000001')
->setPage(1)
->setLimit(25);
$whatsappRecipients = $mailersend->whatsappRecipient->getAll($whatsappRecipientParams);
```
[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.whatsapp.recipient.list({
status: "active",
phone_number: "48600000001",
limit: 25,
page: 1,
})
.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, WhatsAppRecipientsBuilder
from mailersend.models.whatsapp_recipients import WhatsAppRecipientStatus
ms = MailerSendClient()
request = (WhatsAppRecipientsBuilder()
.status(WhatsAppRecipientStatus.ACTIVE)
.phone_number("48600000001")
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_recipients.list_whatsapp_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.ListWhatsAppRecipientOptions{
Status: "active",
PhoneNumber: "48600000001",
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppRecipient.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.whatsapp.recipients.WhatsAppRecipient;
import com.mailersend.sdk.whatsapp.recipients.WhatsAppRecipientList;
public void getWhatsAppRecipients() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppRecipientList list = ms.whatsapp().recipients()
.status("active")
.phoneNumber("48600000001")
.page(1)
.limit(25)
.getRecipients();
for (WhatsAppRecipient recipient : list.recipients) {
System.out.println(recipient.id);
System.out.println(recipient.phoneNumber);
}
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Recipient class
ms_whatsapp_recipient = Mailersend::WhatsAppRecipient.new
# Add parameters
ms_whatsapp_recipient.list(status: 'active', phone_number: '48600000001', page: 1, limit: 25)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `data[].id` | `string` | ID of the recipient. |
| `data[].phone_number` | `string\|null` | The recipient's phone number, when known. |
| `data[].username` | `string\|null` | The recipient's WhatsApp username, when known. |
| `data[].status` | `string` | `active`, `invalid`, `suppressed` or `blocked`. |
| `data[].created_at` | `string` | When the recipient was created, in ISO 8601 format. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "67f91abe2202f37055402301",
"phone_number": "48600000001",
"username": null,
"status": "active",
"created_at": "2026-09-02T08:14:51.000000Z"
},
{
"id": "67f91a0c2202f370554022f4",
"phone_number": "48600000002",
"username": null,
"status": "invalid",
"created_at": "2026-08-30T15:02:11.000000Z"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/recipients?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/recipients?page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/recipients",
"per_page": 25,
"to": 2
}
}
```
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when `status` is not one of the possible values, `phone_number` is not a valid phone number or is longer than 32 characters, or `page` or `limit` is out of range.
*See - [Validation errors](/general#validation-errors)*
## Get a WhatsApp recipient [#get-a-whatsapp-recipient]
Get information about a specific WhatsApp recipient, together with their latest deliveries, with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/recipients/{recipient_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| -------------- | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `recipient_id` | `string` | yes | | The `id` of a recipient, as returned by [`GET` /v1/whatsapp/recipients](#get-a-list-of-whatsapp-recipients). |
```bash
curl --request GET \
--url https://api.mailersend.com/v1/whatsapp/recipients/67f91abe2202f37055402301 \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappRecipient = $mailersend->whatsappRecipient->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.whatsapp.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, WhatsAppRecipientsBuilder
ms = MailerSendClient()
request = (WhatsAppRecipientsBuilder()
.whatsapp_recipient_id("recipient-id")
.build_get_request())
response = ms.whatsapp_recipients.get_whatsapp_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()
_, _, err := ms.WhatsAppRecipient.Get(ctx, "recipient-id")
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.whatsapp.recipients.WhatsAppRecipient;
public void getWhatsAppRecipient() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppRecipient recipient = ms.whatsapp().recipients().getRecipient("recipient id");
System.out.println(recipient.id);
System.out.println(recipient.status);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Recipient class
ms_whatsapp_recipient = Mailersend::WhatsAppRecipient.new
# Add parameters
ms_whatsapp_recipient.get(whatsapp_recipient_id: 'your-whatsapp-recipient-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
The response contains the same fields as an item of [the list](#get-a-list-of-whatsapp-recipients), plus `items`.
| Response key | Type | Details |
| ---------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.items` | `object[]` | The recipient's latest 25 deliveries, newest first. Each entry has the same fields as an item of [`GET` /v1/whatsapp/items](/api/v1/whatsapp/items#get-a-list-of-whatsapp-items). |
| `data.items.*.id` | `string` | ID of the item. Pass it to [`GET` /v1/whatsapp/items/\{item\_id}](/api/v1/whatsapp/items#get-a-whatsapp-item) for its status timeline. |
| `data.items.*.whatsapp_message_id` | `string` | ID of the message the item belongs to. Pass it to [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message). |
| `data.items.*.status` | `string` | `queued`, `sent`, `delivered`, `read` or `failed`. See [WhatsApp status list](/general#whatsapp-status-list). |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "67f91abe2202f37055402301",
"phone_number": "48600000001",
"username": null,
"status": "active",
"created_at": "2026-09-02T08:14:51.000000Z",
"items": [
{
"id": "67f91abe2202f3705540234a",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"from": "15550001234",
"to": "48600000001",
"status": "read",
"template_id": "23zxk54v6gjy6v7m",
"template_name": "Order confirmation",
"error_code": null,
"error_message": null,
"created_at": "2026-10-14T12:25:33.000000Z"
}
]
}
}
```
#### Error [#error-1]
```http
Response Code: 403 Forbidden
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 404 Not Found
```
Returned when the recipient does not exist or belongs to another account.
# Templates (/api/v1/whatsapp/templates)
Every business-initiated WhatsApp message uses a template approved by Meta. Use these requests to look up your templates and their `id`, which you pass as `template_id` to [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message). Templates are created and submitted to Meta in your MailerSend account, under **WhatsApp → Templates**.
Requires a token with one of the `whatsapp_read` or `whatsapp_full` [scopes](/api/v1/account/tokens#possible-scopes).
## Get a list of WhatsApp templates [#get-a-list-of-whatsapp-templates]
Get a list of your WhatsApp templates with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/templates
```
Templates are returned newest first. Templates of a deleted sender are not listed.
#### Request parameters \[!toc] [#request-parameters-toc]
| Query parameter | Type | Required | Limitations | Details |
| --------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `whatsapp_account_id` | `string` | no | Must be one of your WhatsApp senders. | The MailerSend sender ID the templates belong to. See [Sender identifiers](/api/v1/whatsapp#sender-identifiers). |
| `status` | `string` | no | Possible values: `draft`, `pending`, `approved`, `rejected`, `archived`, `deleted`, `disabled`, `flagged`, `in_appeal`, `limit_exceeded`, `locked`, `paused`, `reinstated`, `pending_deletion` | The template's review status. Only `approved` templates can be sent. |
| `category` | `string` | no | Possible values: `UTILITY`, `AUTHENTICATION`, `MARKETING` | |
| `language` | `string` | no | | The template's language code, for example `en_US`. |
| `page` | `int` | no | Min: `1`, Max: `100` | |
| `limit` | `int` | no | Min: `1`, Max: `100` | Default: `25` |
An example request that returns the approved utility templates of one sender:
```http
GET https://api.mailersend.com/v1/whatsapp/templates?whatsapp_account_id=3enl6x27wmrxrl2v&status=approved&category=UTILITY
```
```bash
curl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/templates?whatsapp_account_id=3enl6x27wmrxrl2v&status=approved&category=UTILITY&limit=25' \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WhatsappTemplateParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappTemplateParams = (new WhatsappTemplateParams())
->setWhatsappAccountId('whatsapp_account_id')
->setStatus('approved')
->setCategory('UTILITY')
->setPage(1)
->setLimit(25);
$whatsappTemplates = $mailersend->whatsappTemplate->getAll($whatsappTemplateParams);
```
[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.whatsapp.template.list({
whatsapp_account_id: "whatsapp_account_id",
status: "approved",
category: "UTILITY",
limit: 25,
page: 1,
})
.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, WhatsAppTemplatesBuilder
from mailersend.models.whatsapp_templates import WhatsAppTemplateCategory, WhatsAppTemplateStatus
ms = MailerSendClient()
request = (WhatsAppTemplatesBuilder()
.whatsapp_account_id("whatsapp-account-id")
.status(WhatsAppTemplateStatus.APPROVED)
.category(WhatsAppTemplateCategory.UTILITY)
.page(1)
.limit(25)
.build_list_request())
response = ms.whatsapp_templates.list_whatsapp_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.ListWhatsAppTemplateOptions{
WhatsAppAccountID: "whatsapp-account-id",
Status: "approved",
Category: "UTILITY",
Page: 1,
Limit: 25,
}
_, _, err := ms.WhatsAppTemplate.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.whatsapp.templates.WhatsAppTemplate;
import com.mailersend.sdk.whatsapp.templates.WhatsAppTemplateList;
public void getWhatsAppTemplates() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppTemplateList list = ms.whatsapp().templates()
.whatsappAccountId("whatsapp account id")
.status("approved")
.category("UTILITY")
.page(1)
.limit(25)
.getTemplates();
for (WhatsAppTemplate template : list.templates) {
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"
# Intialize the WhatsApp Templates class
ms_whatsapp_templates = Mailersend::WhatsAppTemplates.new
# Add parameters
ms_whatsapp_templates.list(
whatsapp_account_id: 'your-whatsapp-account-id',
status: 'approved',
category: 'UTILITY',
page: 1,
limit: 25
)
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses]
#### Valid [#valid]
| Response key | Type | Details |
| ---------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `data[].id` | `string` | ID of the template. Use it as `template_id` in [`POST` /v1/whatsapp/send](/api/v1/whatsapp#send-a-whatsapp-message). |
| `data[].whatsapp_account_id` | `string` | The MailerSend sender ID the template belongs to. A template can only be sent from this sender. |
| `data[].name` | `string` | The template name registered with Meta. |
| `data[].readable_name` | `string\|null` | The name of the template shown in your MailerSend account. `null` when no display name is set. |
| `data[].category` | `string` | `UTILITY`, `AUTHENTICATION` or `MARKETING`. |
| `data[].language` | `string` | The template's language code. |
| `data[].status` | `string` | The template's review status, for example `approved`, `pending`, `rejected`, `paused` or `disabled`. |
| `data[].components` | `object` | The content of the template. |
| `data[].components.header` | `object\|null` | The header, or `null` when the template has no header. |
| `data[].components.header.format` | `string` | The header type: `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` or `LOCATION`. |
| `data[].components.header.text` | `string\|null` | The header text, including any variable placeholders. `null` when the header has no text, such as a media header. |
| `data[].components.body` | `object\|null` | The body, or `null` when the template has no body. |
| `data[].components.body.text` | `string\|null` | The body text, including any variable placeholders. `null` when the body has no text. |
| `data[].components.buttons` | `object[]` | The template's buttons, in the order they appear. Empty when the template has no buttons. |
| `data[].components.buttons.*.type` | `string` | The type of button. |
| `data[].components.buttons.*.text` | `string\|null` | The button label. `null` when the button has no label, such as the copy code button of an authentication template. |
| `data[].components.buttons.*.url` | `string\|null` | The URL a URL button opens, otherwise `null`. |
| `data[].created_at` | `string` | When the template was created, in ISO 8601 format. |
| `data[].updated_at` | `string` | When the template was last updated, in ISO 8601 format. |
| `links.first` | `string` | Full URL of the first page, with all your query parameters preserved. |
| `links.last` | `null` | Always `null`. |
| `links.prev` | `string\|null` | Full URL of the previous page. `null` on the first page. |
| `links.next` | `string\|null` | Full URL of the next page. `null` on the last page. |
| `meta.current_page` | `int` | The effective `page`. |
| `meta.current_page_url` | `string` | Full URL of the current page. |
| `meta.from` | `int\|null` | Index of the first row on this page within the result set. `null` when the page is empty. |
| `meta.path` | `string` | The URL of the endpoint, without query parameters. |
| `meta.per_page` | `int` | The effective `limit`. |
| `meta.to` | `int\|null` | Index of the last row on this page within the result set. `null` when the page is empty. |
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": [
{
"id": "23zxk54v6gjy6v7m",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"name": "order_confirmation",
"readable_name": "Order confirmation",
"category": "UTILITY",
"language": "en_US",
"status": "approved",
"components": {
"header": {
"format": "TEXT",
"text": "{{1}}"
},
"body": {
"text": "Hi {{1}}, your order is confirmed and will arrive on {{2}}."
},
"buttons": [
{
"type": "URL",
"text": "View order",
"url": "https://shop.example.com/{{1}}"
}
]
},
"created_at": "2026-10-14T12:25:33.000000Z",
"updated_at": "2026-10-14T12:41:07.000000Z"
},
{
"id": "p6nq4jyzkyv5x3zl",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"name": "delivery_update",
"readable_name": "Delivery update",
"category": "UTILITY",
"language": "en_US",
"status": "pending",
"components": {
"header": null,
"body": {
"text": "Your parcel is out for delivery today."
},
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Change delivery time",
"url": null
}
]
},
"created_at": "2026-10-13T09:02:18.000000Z",
"updated_at": "2026-10-13T09:02:18.000000Z"
}
],
"links": {
"first": "https:\/\/api.mailersend.com\/v1\/whatsapp\/templates?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/api.mailersend.com\/v1\/whatsapp\/templates?page=1",
"from": 1,
"path": "https:\/\/api.mailersend.com\/v1\/whatsapp\/templates",
"per_page": 25,
"to": 2
}
}
```
#### Paginating through the results \[!toc] [#paginating-through-the-results-toc]
The list uses simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`. Follow the URL in `links.next`, which keeps the filters you sent, until it is `null`.
#### Error [#error]
```http
Response Code: 403 Forbidden
```
```json
{
"message": "The custom API token you're using doesn't have the required permissions. #MS40301"
}
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 422 Unprocessable Entity
```
Returned when a parameter is invalid — including a `whatsapp_account_id` that does not belong to your account, a `status` or `category` that is not one of the possible values, or a `page` or `limit` out of range.
*See - [Validation errors](/general#validation-errors)*
## Get a WhatsApp template [#get-a-whatsapp-template]
Get a single WhatsApp template with this `GET` request:
```http
GET https://api.mailersend.com/v1/whatsapp/templates/{template_id}
```
#### Request parameters \[!toc] [#request-parameters-toc-1]
| URL parameter | Type | Required | Limitations | Details |
| ------------- | -------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `template_id` | `string` | yes | | The `id` of a template, as returned by [`GET` /v1/whatsapp/templates](#get-a-list-of-whatsapp-templates). |
```bash
curl --request GET \
--url https://api.mailersend.com/v1/whatsapp/templates/23zxk54v6gjy6v7m \
--header 'Authorization: Bearer API_KEY_HERE'
```
```php
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$whatsappTemplate = $mailersend->whatsappTemplate->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.whatsapp.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, WhatsAppTemplatesBuilder
ms = MailerSendClient()
request = (WhatsAppTemplatesBuilder()
.whatsapp_template_id("template-id")
.build_get_request())
response = ms.whatsapp_templates.get_whatsapp_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()
_, _, err := ms.WhatsAppTemplate.Get(ctx, "template-id")
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.whatsapp.templates.WhatsAppTemplate;
public void getWhatsAppTemplate() {
MailerSend ms = new MailerSend();
ms.setToken("mailersend token");
try {
WhatsAppTemplate template = ms.whatsapp().templates().getTemplate("template id");
System.out.println(template.id);
System.out.println(template.status);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
```
[More examples](https://github.com/mailersend/mailersend-java)
```ruby
require "mailersend-ruby"
# Intialize the WhatsApp Templates class
ms_whatsapp_templates = Mailersend::WhatsAppTemplates.new
# Add parameters
ms_whatsapp_templates.get(whatsapp_template_id: 'your-whatsapp-template-id')
```
[More examples](https://github.com/mailersend/mailersend-ruby)
### Responses [#responses-1]
#### Valid [#valid-1]
The response contains the same fields as an item of [the list](#get-a-list-of-whatsapp-templates).
```http
Response Code: 200 OK
Response Headers:
content-type: application/json
```
```json
{
"data": {
"id": "23zxk54v6gjy6v7m",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"name": "order_confirmation",
"readable_name": "Order confirmation",
"category": "UTILITY",
"language": "en_US",
"status": "approved",
"components": {
"header": {
"format": "TEXT",
"text": "{{1}}"
},
"body": {
"text": "Hi {{1}}, your order is confirmed and will arrive on {{2}}."
},
"buttons": [
{
"type": "URL",
"text": "View order",
"url": "https://shop.example.com/{{1}}"
}
]
},
"created_at": "2026-10-14T12:25:33.000000Z",
"updated_at": "2026-10-14T12:41:07.000000Z"
}
}
```
#### Error [#error-1]
```http
Response Code: 403 Forbidden
```
The token is missing the `whatsapp_read` or `whatsapp_full` scope.
```http
Response Code: 404 Not Found
```
Returned when the template does not exist or belongs to another account.
# Webhooks (/api/v1/whatsapp/webhooks)
WhatsApp webhooks let you subscribe to real-time notifications about the WhatsApp messages you send, and about the messages your recipients send back to you.
Because WhatsApp messages are sent asynchronously, webhooks are the way to be notified of what happened to a message after it was accepted with a `202` response. To look up a message's status on demand instead, use [`GET` /v1/whatsapp/messages/\{message\_id}](/api/v1/whatsapp/messages#get-a-whatsapp-message).
## WhatsApp webhooks overview [#whatsapp-webhooks-overview]
### Setup [#setup]
WhatsApp webhooks are created in your MailerSend account under **WhatsApp → Phone numbers → your sender → Webhooks**. There are no API endpoints for managing WhatsApp webhooks yet.
Each webhook belongs to a single sender and only receives events for messages sent from that sender, or received by it. You choose which events the webhook subscribes to when you create it.
Every webhook has its own signing secret, which you can reveal in the webhook's details.
### Available events [#available-events]
These are all the events you can listen to and send a notification for.
| Event | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `whatsapp.sent` | Fired when your message has been accepted by WhatsApp and sent from our sending servers. |
| `whatsapp.delivered` | Fired when your message is delivered to the recipient's device. |
| `whatsapp.read` | Fired when the recipient opens your message. |
| `whatsapp.failed` | Fired when your message could not be delivered. The payload includes the WhatsApp error code and description. |
| `whatsapp.inbound` | Fired when someone sends a message to your WhatsApp sender. |
### Payload example [#payload-example]
Our responses contain fat payloads, including the information about the event-related object, so there is no need to make an additional API request.
An example of the `whatsapp.delivered` event:
```json
{
"type": "whatsapp.delivered",
"webhook_id": "7z3m5jgrogdpyo6n",
"created_at": "2026-08-31T07:24:20.577080Z",
"data": {
"id": "62f114f7165fe0d8db0288e2",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_item_id": "67f91abe2202f3705540234a",
"type": "delivered",
"template_name": "Order confirmation",
"template_id": "23zxk54v6gjy6v7m",
"from": "15550001234",
"to": "48600000001",
"sender": {
"id": "3enl6x27wmrxrl2v",
"display_name": "Shop Brand",
"phone_number": "15550001234",
"username": "shopbrand"
},
"meta": {
"whatsapp_id": "wamid.HBgLMzcwNjMzMjI3OTcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA"
}
}
}
```
#### Payload fields \[!toc] [#payload-fields-toc]
| Field | Type | Details |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `type` | `string` | The event that triggered the webhook. |
| `webhook_id` | `string` | The ID of the webhook that delivered the event. |
| `created_at` | `string` | When the event was created, in ISO 8601 format. |
| `data.id` | `string` | The ID of the activity record for this event. |
| `data.whatsapp_account_id` | `string` | The MailerSend ID of the sender the message was sent from. |
| `data.whatsapp_message_id` | `string` | The ID returned when the message was sent. One message can have up to 10 recipients. |
| `data.whatsapp_item_id` | `string` | The ID of the message for this single recipient. Use it to follow one recipient through all events. |
| `data.type` | `string` | The status: `sent`, `delivered`, `read` or `failed`. |
| `data.template_name` | `string` | The name of the template that was sent. |
| `data.template_id` | `string` | The ID of the template that was sent. |
| `data.from` | `string` | The sender's phone number or username. Display only — it is an empty string for a sender connected with a Meta virtual number. |
| `data.to` | `string` | The recipient's phone number or BSUID. |
| `data.sender` | `object` | The sender the message was sent from. |
| `data.sender.id` | `string` | The MailerSend sender ID. Same value as `data.whatsapp_account_id`. |
| `data.sender.display_name` | `string` | The display name shown to recipients. |
| `data.sender.phone_number` | `string\|null` | `null` for a sender connected with a Meta virtual number. |
| `data.sender.username` | `string\|null` | `null` if the sender has not claimed a WhatsApp username. |
| `data.meta` | `object\|null` | Extra information about the event. Carries `whatsapp_id` on success and the error details on failure. |
Use `data.whatsapp_account_id` or `data.sender.id` to group and join events by sender. `data.from` is display only and can be empty.
### Failed messages [#failed-messages]
The `whatsapp.failed` event carries the error reported by WhatsApp in `data.meta`, together with a human-readable title and description so you can act on it without looking the code up.
```json
{
"type": "whatsapp.failed",
"webhook_id": "7z3m5jgrogdpyo6n",
"created_at": "2026-08-31T07:24:20.577080Z",
"data": {
"id": "62f114f7165fe0d8db0288e2",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"whatsapp_message_id": "67f91abd69f79df391e9d78d",
"whatsapp_item_id": "67f91abe2202f3705540234a",
"type": "failed",
"template_name": "Order confirmation",
"template_id": "23zxk54v6gjy6v7m",
"from": "15550001234",
"to": "48600000001",
"sender": {
"id": "3enl6x27wmrxrl2v",
"display_name": "Shop Brand",
"phone_number": "15550001234",
"username": "shopbrand"
},
"meta": {
"error_code": 131026,
"error_message": "Message undeliverable",
"error_title": "Message Undeliverable",
"error_description": "Unable to deliver the message. Common reasons include the recipient's phone number being invalid, not registered on WhatsApp, or otherwise unable to receive messages."
}
}
}
```
| Field | Type | Details |
| ------------------------ | -------------- | --------------------------------------------- |
| `meta.error_code` | `integer` | The WhatsApp Cloud API error code. |
| `meta.error_message` | `string` | The raw message returned by WhatsApp. |
| `meta.error_title` | `string\|null` | A short name for the error. |
| `meta.error_description` | `string\|null` | What the error means and what to do about it. |
See Meta's [error code reference](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes) for the full list of codes.
### Inbound messages [#inbound-messages]
The `whatsapp.inbound` event is fired when someone sends a message to your WhatsApp sender, including replies to your template messages and button taps.
```json
{
"type": "whatsapp.inbound",
"webhook_id": "7z3m5jgrogdpyo6n",
"created_at": "2026-08-31T07:24:20.577080Z",
"data": {
"id": "62f114f7165fe0d8db0288e2",
"whatsapp_account_id": "3enl6x27wmrxrl2v",
"whatsapp_inbound_message_id": "62f114f7165fe0d8db0288e2",
"meta_message_id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA",
"from": "48600000001",
"to": "15550001234",
"sender": {
"id": "3enl6x27wmrxrl2v",
"display_name": "Shop Brand",
"phone_number": "15550001234",
"username": "shopbrand"
},
"received_at": "2026-08-31T07:24:19.000000Z",
"type": "text",
"text": {
"body": "Hello, I would like to check my order status."
},
"context": {
"message_id": "wamid.HBgLMzcwNjMzMjI3OTcVAgARGBIwREE3N0EwN0EyNjhENjEwOEMA"
}
}
}
```
| Field | Type | Details |
| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `data.id` | `string` | The ID of the inbound message. |
| `data.whatsapp_inbound_message_id` | `string` | Same value as `data.id`. |
| `data.meta_message_id` | `string` | WhatsApp's own message ID. |
| `data.from` | `string` | The phone number of the person who sent the message. |
| `data.to` | `string` | Your sender's phone number. Empty for a sender connected with a Meta virtual number. |
| `data.received_at` | `string` | When WhatsApp received the message, in ISO 8601 format. |
| `data.type` | `string` | The kind of message. See the table below. |
| `data.context` | `object` | Present when the message is a reply. `context.message_id` is the WhatsApp ID of the message that was replied to. |
The `data.type` field determines which additional field is present in the payload:
| `type` | Additional field | Contents |
| ------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| `text` | `text` | `body` with the message text. |
| `image`, `audio`, `video`, `document`, `sticker` | `attachment` | The downloaded media file. See [Media attachments](#media-attachments). |
| `location` | `location` | `latitude`, `longitude`, and `name` and `address` when shared. |
| `contacts` | `contacts` | The shared contact cards, as sent by WhatsApp. |
| `reaction` | `reaction` | `emoji` and the `message_id` of the message that was reacted to. |
| `button` | `button` | `text` and `payload` of the quick reply button that was tapped. |
| `interactive` | `list_reply` or `interactive` | `id`, `title` and `description` for a list reply, or the raw interactive payload for other subtypes. |
| `order`, `system`, `unknown`, `unsupported` | matching the type | The raw payload as sent by WhatsApp. |
#### Media attachments [#media-attachments]
Media in an inbound message is downloaded and stored by MailerSend, and the payload carries a temporary signed URL to it.
```json
{
"type": "image",
"attachment": {
"url": "https://app.mailersend.com/whatsapp/inbound-message-attachment/62f114f7165fe0d8db0288e2?account=3enl6x27wmrxrl2v&expires=1790000000&signature=...",
"status": "stored",
"mime_type": "image/jpeg",
"size": 102400,
"caption": "Here is the damaged item"
}
}
```
| Field | Type | Details |
| ---------------------- | -------------- | ------------------------------------------------------------------------------ |
| `attachment.url` | `string\|null` | A temporary signed URL to the file. `null` when the download failed. |
| `attachment.status` | `string` | `stored` when the file is available, `failed` when it could not be downloaded. |
| `attachment.mime_type` | `string` | The media type reported by WhatsApp. |
| `attachment.size` | `integer` | The file size in bytes. |
| `attachment.caption` | `string` | The caption, when the sender added one. |
| `attachment.filename` | `string` | The original file name, for documents. |
| `attachment.animated` | `boolean` | Present for stickers only. |
Inbound media is kept for 1 day and the signed URL expires with it. Download the file as soon as you receive the event if you need to keep it.
### Security [#security]
Webhook requests made by MailerSend include a `Signature` header. It contains a string generated by hashing the data sent to your webhook endpoint with an individual Signing Secret. A signing secret is a random string that is generated when you create a webhook.
**Verifying a signature:**
```php
// $signature - a header sent by MailerSend, please refer to your framework
// or PHP manual on how to read the Signature header
// $requestContent - please refer to your framework or PHP manual on how to read the request content
$computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
return hash_equals($signature, $computedSignature);
```
### Testing webhooks [#testing-webhooks]
You can send a test event to your endpoint from the webhook's details in your MailerSend account. Test events use the same structure as real ones and are signed with your webhook's signing secret.
The webhook's log shows every delivery attempt, the response code your endpoint returned, and lets you retry a failed attempt.
If your endpoint is unreachable or returns a non-2xx response, MailerSend automatically retries with exponential backoff for up to about 3 days. While your webhook is failing we'll send escalating email notifications. If the endpoint stays down too long, the webhook is automatically paused. You can re-enable it from your dashboard at any time.
### Retrying failed webhooks [#retrying-failed-webhooks]
When your webhook receives a response other than a `2xx` code from your endpoint URL, or if the endpoint doesn't respond within 3 seconds, it will show up as a failed attempt in the log section of your webhook. If it receives a `2xx`, then it will show as a success.
If a webhook call fails, MailerSend automatically retries with exponential backoff for up to about 3 days.
### Useful tools [#useful-tools]
[Webhook.site](https://webhook.site/) or [Pipedream.com](https://pipedream.com/) are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.