MailerSend
WhatsApp API

Recipients

Retrieve the WhatsApp recipients of your account with the MailerSend API. Get a list of recipients filtered by status or phone number, or a single recipient with their latest deliveries.

Get information about the people you have sent WhatsApp messages to.

Required token scopes

Requires a token with one of the whatsapp_read or whatsapp_full scopes.

Get a list of WhatsApp recipients

Get a list of WhatsApp recipients with this GET request:

GET https://api.mailersend.com/v1/whatsapp/recipients

Recipients are returned newest first.

Request parameters

Query parameterTypeRequiredLimitationsDetails
statusstringnoactive, invalid, suppressed, blocked
phone_numberstringnoMax: 32 charactersThe 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.
pageintnoMin: 1, Max: 100
limitintnoMin: 1, Max: 100Default: 25
curl --request GET \
  --url 'https://api.mailersend.com/v1/whatsapp/recipients?status=active&phone_number=48600000001&limit=25' \
  --header 'Authorization: Bearer API_KEY_HERE'
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

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

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

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

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

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

Responses

Valid

Response keyTypeDetails
data[].idstringID of the recipient.
data[].phone_numberstring|nullThe recipient's phone number, when known.
data[].usernamestring|nullThe recipient's WhatsApp username, when known.
data[].statusstringactive, invalid, suppressed or blocked.
data[].created_atstringWhen the recipient was created, 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": "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

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 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

Get a WhatsApp recipient

Get information about a specific WhatsApp recipient, together with their latest deliveries, with this GET request:

GET https://api.mailersend.com/v1/whatsapp/recipients/{recipient_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
recipient_idstringyesThe id of a recipient, as returned by GET /v1/whatsapp/recipients.
curl --request GET \
  --url https://api.mailersend.com/v1/whatsapp/recipients/67f91abe2202f37055402301 \
  --header 'Authorization: Bearer API_KEY_HERE'
use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$whatsappRecipient = $mailersend->whatsappRecipient->find('recipient_id');

More examples

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

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

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

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

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

Responses

Valid

The response contains the same fields as an item of the list, plus items.

Response keyTypeDetails
data.itemsobject[]The recipient's latest 25 deliveries, newest first. Each entry has the same fields as an item of GET /v1/whatsapp/items.
data.items.*.idstringID of the item. Pass it to GET /v1/whatsapp/items/{item_id} for its status timeline.
data.items.*.whatsapp_message_idstringID of the message the item belongs to. Pass it to GET /v1/whatsapp/messages/{message_id}.
data.items.*.statusstringqueued, sent, delivered, read or failed. See WhatsApp status list.
Response Code: 200 OK
Response Headers:
	content-type: application/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

Response Code: 403 Forbidden

The token is missing the whatsapp_read or whatsapp_full scope.

Response Code: 404 Not Found

Returned when the recipient does not exist or belongs to another account.

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.

Templates

Retrieve the WhatsApp templates of your account with the MailerSend API. Get a list of templates filtered by sender, status, category and language, or a single template.

On this page

Get a list of WhatsApp recipientsResponsesValidErrorGet a WhatsApp recipientResponsesValidError