Create contacts in bulk
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).
Authorization
apiKey An API key from the dashboard (ms_…), sent as Authorization: Bearer. A sending-only key reaches the /emails routes only.
In: header
Query Parameters
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).
"error"Value in
- "error"
- "skip"
- "upsert"
Header Parameters
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
1 <= items <= 1000A 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" } ]}