Creates or updates one contact by e-mail and returns it whole, as get_contact does. Call it to push a contact from another system, such as a CRM, without looking it up first; for many contacts at once, upsert_contacts.

The contact is found by email, without case, and updated; when the address is free it is created. The address of a deleted contact restores that contact with its old data and applies the request over it. result says which: created and restored answer 201, updated and unchanged (nothing to change, nothing written) answer 200.

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.