Activities
Retrieve the status events of your WhatsApp messages with the MailerSend API. Get a list of activities filtered by message, item, recipient, type and date.
An activity is a single status event of an item, 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.
Required token scopes
Requires a token with one of the whatsapp_read or whatsapp_full scopes.
Data retention
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 the status events of your WhatsApp messages with this GET request:
GET https://api.mailersend.com/v1/whatsapp/activitiesActivities 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}.
Request parameters
| 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. | |
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
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:
GET https://api.mailersend.com/v1/whatsapp/activities?whatsapp_message_id=67f91abd69f79df391e9d78dcurl --request GET \
--url 'https://api.mailersend.com/v1/whatsapp/activities?whatsapp_message_id=67f91abd69f79df391e9d78d&limit=25' \
--header 'Authorization: Bearer API_KEY_HERE'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);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));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)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)
}
}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();
}
}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)Responses
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}. |
data[].whatsapp_message_id | string | ID of the message the activity belongs to. Pass it to GET /v1/whatsapp/messages/{message_id}. |
data[].whatsapp_account_id | string|null | The MailerSend sender ID of the phone number the message was sent from. See 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. |
Response Code: 200 OK
Response Headers:
content-type: application/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
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
Response Code: 403 Forbidden{
"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.
Response Code: 422 Unprocessable EntityReturned 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
Items
Retrieve the delivery of your WhatsApp messages to each recipient with the MailerSend API. Get a list of items filtered by recipient, status and date, or a single item with its status timeline.
Inbound messages
Retrieve the WhatsApp messages your customers sent to your phone numbers with the MailerSend API. Filter by phone number, customer, message type and date.