MepMail Docs
API referenceEndpointsContactsBatch

Create contacts in bulk

POST
/contacts/batch

MepMail extension: creates up to 1000 contacts in one request (Resend imports contacts only via CSV). Each item is a CreateContactRequest. on_conflict decides what happens to an email that already belongs to a contact — error (default), skip, or upsert. An upsert updates first_name/last_name only when provided, merges properties (provided keys overwrite), adds segments and upserts topics. unsubscribed: true opts the contact out; unsubscribed: false on an already unsubscribed contact is ignored — a batch never re-subscribes anyone, that stays an explicit PATCH /contacts/{id}. The x-batch-validation header picks strict (default, all-or-nothing) or permissive (valid subset written, failures listed in errors).

AuthorizationBearer <token>

An API key from the dashboard (ms_…), sent as Authorization: Bearer. A sending-only key reaches the /emails routes only.

In: header

Query Parameters

on_conflict?string

What to do with an item whose email (case-insensitive) already belongs to a contact: error fails the item, skip leaves the contact untouched and reports its id, upsert merges the item into it. Also decides how an email repeated inside the batch is handled: error fails the later occurrence, skip keeps the first, upsert collapses them into one write (later scalar fields win, associations are unioned).

Default"error"

Value in

  • "error"
  • "skip"
  • "upsert"

Header Parameters

x-batch-validation?string

strict (default): any invalid item rejects the whole batch with that item's status and a contacts.{index}: message prefix, writing nothing. permissive: invalid items are listed in errors and the valid subset is written.

Value in

  • "strict"
  • "permissive"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

1-1000 CreateContactRequest items

Items1 <= items <= 1000
[index: integer]?unknown

A CreateContactRequest item

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/contacts/batch" \  -H "Content-Type: application/json" \  -d '[    {      "email": "customer@example.com",      "first_name": "Ana"    },    {      "email": "another@example.com",      "unsubscribed": true    }  ]'
{  "data": [    {      "object": "contact",      "index": 1,      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",      "status": "created"    }  ],  "counts": {    "created": 1,    "updated": 1,    "skipped": 1,    "failed": 1  },  "errors": [    {      "index": 1,      "message": "A human-readable explanation"    }  ]}