Creates or updates contacts by e-mail, up to 100 per call: each item finds the contact by email, without case, and updates it, or creates it when the address is free. Call it to add a list of people or to sync many contacts from another system without looking each one up first. One contact with the contact back in the answer is upsert_contact.

The answer reports every item in the order given: created, updated, restored (the address belonged to a deleted contact, which is back with its old data and the item applied over it), unchanged or failed with a reason; one failed item writes nothing of its own and does not stop the others.

A field left out is kept; null clears first_name, last_name, phone, country, timezone and language; fields are keyed by field ids from list_contact_fields, merged by key, and null removes a value. Tags go by name, compared without case: add_tags adds them and creates a tag the site does not have, remove_tags takes them off; tags not named stay. changed names the fields that were written.

Status: subscribed is allowed from unsubscribed, and subscribes again a contact who opted out, as the admin does; leave status out to keep what the contact chose. unsubscribed is allowed from subscribed or from awaiting double opt-in. A bounced contact changes status only with a new e-mail, and a contact awaiting double opt-in is never subscribed here. A status change that is not allowed does not stop the rest: the other fields are written and reason says why.

A new contact is subscribed unless status says unsubscribed, which stores it as never subscribed; it cannot be created bounced. Its source is api, with the API key as id, or the user when the call is made with a user's access token. A contact created here starts "new contact" automations when subscribed and emits contact.created; a restored one does neither. Its e-mail is checked in the background. A found contact keeps the stored case of its e-mail and its source.

Items of one contact, here, in upsert_contact, update_contacts and delete_contacts, run one after another, so concurrent calls keep each other's tags and field keys.