Engagement rules
An engagement rule controls how recipients interact with warmup mail from an address: how often it is replied to, marked important, or clicked. Each address carries exactly one rule.
1. Standard rules
GET /engagement-rules returns the catalogue:
- IDNameNotes
- -1CustomSet automatically when a custom rule is created. Cannot be assigned directly.
- 0DefaultStandard warmup pace.
- 1Slow PaceLower volume ramp.
- 2RepairFor an address recovering from deliverability problems.
- 3BoostHigher engagement.
- 4ProtectConservative, for an address with an established reputation.
To change the rule on an address:
Returns 204. rule_id must be 0 to 4. -1 is rejected here, because a custom rule is created through the endpoints in section 7.2.
2. Custom engagement rules
A custom rule replaces the standard rule with your own engagement percentages. Creating one sets the address to engagement_rule_id: -1.
- FieldRange
reply_pct5 to 45important_pct5 to 40click_pct0 to 70, and no more than important_pct × 1.75
Create
Returns 200 with can_update: false and remaining_seconds of roughly 604800. A second create on the same address returns 409.
Read
URL-encode the @ in the path.
Update
Same body as create, sent with PUT. Returns 200 once the cooldown has expired, 429 while it is still running, and 404 with "Use POST to create one" if the address has no custom rule yet.
Delete
Deleting a custom rule restores a standard rule, so the request has to say which one. engagement_rule_id here is the standard rule to fall back to, not the identifier of the custom rule. It must be 1 or higher, so 1 to 4 are the valid choices.
Returns 200 {"status":"ok","deleted":true}.
- RequestResponse
- Parameters sent in the query string instead of a body422
- engagement_rule_id that is not a standard rule400 engagement_rule_id does not exist
- Valid engagement_rule_id, address has no custom rule404
The rule identifier is checked before the address is looked up. A request that gets both wrong returns 400 for the rule, not 404 for the address.
After a delete, the address can have a new custom rule created immediately. That create starts a fresh 7 day cooldown.
Was this page helpful?
