curl --request POST \
--url https://cloudapi.mailercloud.com/v1/contacts/upsert \
--header 'Authorization: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '
{
"city": "San Francisco",
"country": "USA",
"custom_fields": {
"enc_id1": "ABC123",
"personalisation_tag_4": 456
},
"department": "Engineering",
"email": "john.doe@example.com",
"industry": "Software Development",
"job_title": "Software Engineer",
"last_name": "Doe",
"lead_source": "Website",
"list_id": "KYHH",
"middle_name": "A.",
"first_name": "John A. Doe",
"company_name": "Tech Innovations Inc.",
"phone": "+1-234-567-8901",
"salary": 95000,
"state": "California",
"postal_code": "94105",
"contact_type": "active",
"tags": [
"prospect",
"customer",
"lead"
]
}
'{
"contact_id": "fZuKHSuwK",
"status": "updated"
}Create or Update Contact
API to manage your contacts, allowing you to either create new contacts or update existing ones based on your needs.
When you send a request, the API first checks if the contact already exists in your database. If the contact is found, the API will automatically update the existing contact with the new information provided. This ensures that your contact list remains up-to-date without creating duplicates.
Custom Property Data: The API allows you to add custom properties to each contact. You can do this in two ways:
- By Property ID: Map the property ID to its corresponding value.
- By Personalization Tag: Alternatively, you can use personalization tag for that property to specify values.
Contact Quota Limit: Please note that you can continue adding or updating contacts until you reach your designated contact quota limit. If you reach your quota limit, further attempts to add new contacts will be rejected until you either remove some existing contacts or increase your quota.
curl --request POST \
--url https://cloudapi.mailercloud.com/v1/contacts/upsert \
--header 'Authorization: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '
{
"city": "San Francisco",
"country": "USA",
"custom_fields": {
"enc_id1": "ABC123",
"personalisation_tag_4": 456
},
"department": "Engineering",
"email": "john.doe@example.com",
"industry": "Software Development",
"job_title": "Software Engineer",
"last_name": "Doe",
"lead_source": "Website",
"list_id": "KYHH",
"middle_name": "A.",
"first_name": "John A. Doe",
"company_name": "Tech Innovations Inc.",
"phone": "+1-234-567-8901",
"salary": 95000,
"state": "California",
"postal_code": "94105",
"contact_type": "active",
"tags": [
"prospect",
"customer",
"lead"
]
}
'{
"contact_id": "fZuKHSuwK",
"status": "updated"
}Authorizations
Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API.
Headers
Request body type
Body
Show child attributes
Show child attributes
Open-tracking consent for this contact.
Accepted values are case-insensitive and whitespace-trimmed:
- granted:
granted,yes,true,1,subscribed - denied:
denied,revoked,no,false,0,unsubscribed - unknown:
unknown,never subscribed
The subscribed / unsubscribed / never subscribed aliases let Klaviyo exports be imported unchanged.
An unrecognised or empty value is ignored and leaves any existing consent untouched - it is not a validation error, so a blank field in a re-upload never erases a previously recorded answer.
Setting a value also stamps tracking_consent_date and sets tracking_consent_source to 5 (API). Those two fields cannot be set directly.
Maximum: 20
20