MailerSend
WhatsApp API

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/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}.

Request parameters

Query parameterTypeRequiredLimitationsDetails
whatsapp_item_idstringnoThe ID of the item the activities belong to.
whatsapp_message_idstringnoThe ID of the message the activities belong to.
recipientstringnoThe recipient's phone number in international format, WhatsApp username or BSUID. See Filtering.
type[]string[]noPossible values: queued, sent, delivered, read, failedArray only. Multiple values are combined with OR.
date_fromint|stringnoTimestamp 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_toint|stringnoTimestamp 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.
pageintnoMin: 1, Max: 100To reach older activities beyond page 100, narrow date_from and date_to.
limitintnoMin: 1, Max: 100Default: 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=67f91abd69f79df391e9d78d
curl --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);

More examples

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

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

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

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

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

Responses

Valid

Response keyTypeDetails
data[].idstringID of the activity.
data[].whatsapp_item_idstringID of the item the activity belongs to. Pass it to GET /v1/whatsapp/items/{item_id}.
data[].whatsapp_message_idstringID of the message the activity belongs to. Pass it to GET /v1/whatsapp/messages/{message_id}.
data[].whatsapp_account_idstring|nullThe MailerSend sender ID of the phone number the message was sent from. See Sender identifiers.
data[].fromstring|nullThe 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[].tostringThe recipient's phone number or BSUID.
data[].typestringThe status that was recorded: queued, sent, delivered, read or failed.
data[].created_atstringWhen the status was recorded, in ISO 8601 format.
links.firststringFull URL of the first page, with all your query parameters preserved.
links.lastnullAlways null.
links.prevstring|nullFull URL of the previous page. null on the first page.
links.nextstring|nullFull URL of the next page. null on the last page.
meta.current_pageintThe effective page.
meta.current_page_urlstringFull URL of the current page.
meta.fromint|nullIndex of the first row on this page within the result set. null when the page is empty.
meta.pathstringThe URL of the endpoint, without query parameters.
meta.per_pageintThe effective limit.
meta.toint|nullIndex 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 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

On this page