Skip to main content
ZeroBounce Docs logo
Log InSign Up Free
  • Home
  • Getting started
  • Products
  • API
  • Integrations
  • FAQ
  • About ZeroBounce
Browse documentation
ZeroBounce Docs logo
  • Getting started
  • Products
  • API
  • Integrations
  • FAQ
  • About ZeroBounce

Type at least 2 characters to search the docs.

↑↓ Navigate↵ OpenEsc Close

Docs Assistant

Answers written from the ZeroBounce documentation

Hi! I'm your ZeroBounce Docs Assistant. How can I help you with our APIs or integrations today?

Try Asking

Loading suggestions...

AI-generated from our docs. Check important details against the linked pages.

API

  • Email Validation API
  • Inbox Placement Tester API
  • Warmup API
    • Overview
    • Authentication
    • Response and error model
    • Endpoint reference
    • Adding a sending account
    • Updating a sending account
    • Engagement rules
    • Statistics and utilities
    • Rate limits
    • Data isolation
    • Quickstart
  • Activity Data API
  • List Evaluator API
  • Email Finder API
  • Domain Search API
  • A.I. Scoring API
  • Api Dashboard
  • API Wrappers
  • API Migration
  1. Home
  2. Warmup API
  3. Engagement rules

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:

  • ID
    Name
    Notes
  • -1
    Custom
    Set automatically when a custom rule is created. Cannot be assigned directly.
  • 0
    Default
    Standard warmup pace.
  • 1
    Slow Pace
    Lower volume ramp.
  • 2
    Repair
    For an address recovering from deliverability problems.
  • 3
    Boost
    Higher engagement.
  • 4
    Protect
    Conservative, 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.

  • Field
    Range
  • reply_pct
    5 to 45
  • important_pct
    5 to 40
  • click_pct
    0 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.

Creating a custom rule starts a 7 day cooldown. Any PUT /custom-engagement inside that window returns 429 with the remaining seconds. Read can_update and remaining_seconds from the create or GET response and gate your own update calls on them.

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}.

  • Request
    Response
  • Parameters sent in the query string instead of a body
    422
  • engagement_rule_id that is not a standard rule
    400 engagement_rule_id does not exist
  • Valid engagement_rule_id, address has no custom rule
    404

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?

PreviousUpdating a sending accountNextStatistics and utilities
Interested in our partner programs?
Partner program

Interested in our partner programs?