MepMail Docs

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

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

curl -X POST "https://example.com/contacts/batch" \  -H "Content-Type: application/json" \  -d '[    null  ]'
{  "data": [    {      "object": "contact",      "index": 0,      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "status": "created"    }  ],  "counts": {    "created": 0,    "updated": 0,    "skipped": 0,    "failed": 0  },  "errors": [    {      "index": 0,      "message": "string"    }  ]}