This use case shows how to set the tracking type of a prepared message through the Engage API. The tracking type decides how each recipient's tracking consent is applied to that message. It is sent as the trackingOverride field on the /preparedmessage/update call. For what the options mean and what the anonymized option does and does not deliver, 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 prepared message you want to update must already exist.
Consent-aware outgoing tracking must be active for your account. This is part of the standard Tracking Consent setup and is not specific to this feature.
The trackingOverride field
The field takes one of three values. Any other value is rejected.
Value | Option in the interface | Behaviour |
|---|---|---|
| Normal Tracking | No override. Each recipient's tracking consent applies. This is the default. |
| Force Full Tracking | Open and click tracking are enforced for all recipients with their real contact identifier, regardless of individual consent. |
| Force Anonymized When Denied or Withdrawn | Recipients who granted consent are tracked normally. Recipients who denied or withdrew consent receive tracking URLs carrying an anonymous placeholder instead of their contact identifier, and their opens and clicks count towards aggregate statistics only. |
Note
On update, omitting
trackingOverrideor sendingnullpreserves the value already stored on the message. To clear an active override, send1explicitly. Omitting the field does not reset it.
Warning
The tracking type only takes effect when consent-aware outgoing tracking is active for your account. If it is not, consent handling is skipped entirely and the message is tracked with the real contact identifier, whichever value you send. The API does not return an error in that case.
Procedure
The update call carries the whole prepared message in its body, not just the fields you want to change. Read the current record first, then send it back with trackingOverride set to the value you want. Only trackingOverride is documented as preserving its stored value when omitted; for the remaining fields, send back what you read.
1. Read the current record
GET 'https://your-engage-domain.com/api/rest/preparedmessage/get?messageId=7579&contactId=45802709'The response contains the identifying fields, the nested message object with the subject and body, and the current trackingOverride.
2. Send the record back with the new tracking type
Take the response from step 1, change trackingOverride, and post it back unchanged otherwise. The example below selects anonymized tracking for recipients who denied or withdrew consent. The message object is shortened here for readability; send it exactly as you received it.
POST 'https://your-engage-domain.com/api/rest/preparedmessage/update' \
{
"contactId": 45802709,
"messageId": 7579,
"name": "SpringNewsletter2026",
"groupId": 3302,
"groupName": "Newsletter",
"selectionId": null,
"selectionName": null,
"channelId": 327699,
"channelName": "DMC Email",
"externalId": null,
"messageCategoryId": null,
"messageCategoryName": null,
"trackingOverride": 3,
"message": {
"subject": "Our spring highlights",
"emailBodyHtml": "<html>…</html>"
}
}Warning
Do not send a body that contains only the identifiers and
trackingOverride. The documentation does not state which fields the call preserves, so a shortened body risks overwriting the subject, the message body or other settings of the prepared message.
To read the value back afterwards, call /preparedmessage/get again. It returns trackingOverride alongside the other message fields.
Conclusion
You should receive a 204 response and no further information, which indicates the prepared message has been updated. If there was a problem, you might receive a 400 response.