This use case shows how to set a contact's email tracking consent through the Engage API. The consent state is stored in custom attributes on the contact profile and is sent using the existing /contact/update call — the same way as any other attribute. For what the feature does and what each value means, see Email Tracking Consent.
Prerequisites
Before you begin, make sure you have valid authorization credentials. See Getting Started with Engage API for more information. The contact you want to update must already exist; if it does not, create it first.
The tracking consent attributes
Three custom attributes hold the consent information:
Attribute | Description |
|---|---|
tracking_consent | The consent state. One of: granted, denied, withdrawn, unknown. A value of unknown means no preference is stored, in which case tracking remains on by default. |
tracking_consent_source | Where or how the consent was collected (for example, a preference centre or a registration form). The value is defined by you. |
tracking_consent_source_id | An identifier for the specific source or consent record (for example, a form or version identifier). The value is defined by you. |
Note
These are custom attributes, so the API does not enforce them or validate their values. To stay compliant, set at least tracking_consent and tracking_consent_source; tracking_consent_source_id is recommended. Mapp stores exactly what you send and does not validate it — the accuracy of the data is your responsibility.
Procedure
Send the attributes in the attributes array of a /contact/update POST request, exactly as you would for any other attribute. The example below sets a denied consent for a contact identified by email.
POST 'https://your-engage-domain.com/api/rest/contact/update?identifierType=EMAIL&unifiedIdentifierName=j.mcexample%40example.com' \
{
"emailAddress": "j.mcexample@example.com",
"attributes":
[
{"name": "tracking_consent", "value": "denied"},
{"name": "tracking_consent_source", "value": "preference_center"},
{"name": "tracking_consent_source_id", "value": "pc-2026-07-01"}
]
}Conclusion
You should receive a 204 response and no further information, which indicates the profile has been updated. If there was a problem, you might receive a 400 response.
Related Topics
Updating a Contact's Information