---
title: "Read contacts in bulk"
method: POST
path: "/contacts/batch/get"
tags: ["Contacts"]
---

# Read contacts in bulk

`POST /contacts/batch/get`

## Request

- Base URL: `https://api.mepmail.dev`
- URL: `https://api.mepmail.dev/contacts/batch/get`
- Auth: HTTP bearer

MepMail extension: returns up to 1000 contacts by id or by email address in one request, in request order, optionally with their properties and topic subscriptions. Entries that match no contact are listed under `missing` instead of failing the call. One call counts as one request against the rate limit.

## Request body

- BatchGetContactsRequest
  - `contacts` object[], required: Up to 1000 contacts, each by id or by email address (matched case-insensitively)
    - `id` string, uuid
    - `email` string, email
  - `include` string[]: Facets to attach to every contact returned: properties and/or topics

## Response `200`

The contacts found, and the entries that matched none

- BatchGetContactsResponse
  - `object` 'list', required
  - `data` object[], required: The contacts found, in request order
    - `id` string, uuid, required
    - `email` string, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `created_at` string, required
    - `unsubscribed` boolean, required
    - `properties` object: Present with include=properties
    - `topics` object[]: Present with include=topics
      - `id` string, uuid, required
      - `name` string, required
      - `description` string, nullable, required
      - `subscription` 'opt_in' | 'opt_out', required: Effective choice: the contact's explicit one, else the topic's default
      - `explicit` boolean, required: True when the contact or the API chose this; false when it is the topic's default
      - `visibility` 'public' | 'private', required: The hosted preference page lists public topics only
    - `object` 'contact', required
  - `missing` object[], required: Request entries that matched no contact of the team
    - `index` integer, required: Position in the request's contacts array
    - `id` string, uuid
    - `email` string

## Other responses

- `401`: Missing, malformed or invalid API key
- `422`: Validation error
- `429`: Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After

---

[API](https://skmtc.dev/mepmail/apis/mepmail-api.md) · [All operations](https://skmtc.dev/mepmail/apis/mepmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mepmail/apis/mepmail-api/revisions/262a89f73730?raw)