Custom Filter Rules for AllowList and BlockList

The ZeroBounce email validationⓘ API offers the possibility of using custom filter rules to create personalized allow and block lists. They can be placed at the email, domain, mx record level or TLD (Top Level Domain).

Getting started

The validation process checks whether there is a matching record in your filter rule list. When one is found, the status and sub_status of the email being validated will be set as follows:

Allow

    "status": "valid"
    "sub_status": "allowed"
  

Block

     "status": "do_not_mail"
     "sub_status": "blocked"
  

Important Note
The more specific the rule, the higher its matching priority.
email > domain > tld > mx

For example:

api_key: your API key
rule: block
target: email
value: test@example.com

Overrides

api_key: your API key
rule: allow
target: domain
value: example.com

All fields are mandatory.

Add or Modify “allow” or “block” rule

This allows you to create custom filter rules to allow or block specific emails, email domains, mx records or tld. For the latter, you can also use an asterisk (*) at the front to denote a wildcard for mx records.

Automatically block untrusted senders and domains, and automatically allow otherwise trusted parties to begin the email validationⓘ process.

In order to modify a rule, send the same “target” and “value” fields, but change the “rule”.

Below is an example Java code of how to add a rule using the API. You must have a ZeroBounce account and access to your API key to add a custom filter rule.

Please allow up to 1 minute for changes to propagate.

There are no limits to the number of filters you can set for allow/block.

When validating an email from the allow/block list, credits will still be deducted.

API DEFAULT URL: https://api.zerobounce.net/v2/filters/add

API U.S.A. URL*: api-us.zerobounce.net/v2/filters/add

API EU URL: api-eu.zerobounce$.net/v2/filters/add

Method: POST

Content-Type: application/x-www-form-urlencoded

*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.

Successful Response

    {"Message": "Filter successfully added"}
    {"Message": "Filter successfully updated"}
  

Unsuccessful Response

    {"Message": "Filter already exists"}

Error Response

    {"Error": "Invalid API key or your account ran out of credits"}
    {"Error": "Missing param: api_key"}
    {"Error": "Missing param: rule"}
    {"Error": "Missing param: target"}
    {"Error": "Missing param: value"}
    {"Error": "Allowed values for rule: allow, block"}
    {"Error": "Allowed values for target: email, domain, mx, tld"}
    {"Error": "Bad email syntax for param: value"}
    {"Error": "Bad domain syntax for param: value"}
    {"Error": "Invalid request format"}

After receiving a successful response, your custom filter will automatically allow or block any email, domain, mx or tld that matches your rule.

Code samples

Delete a custom filter rule

This will enable you to delete any existing allow or block rules. If you no longer need to block a specific email, domain, mx or tld, consider deleting the rule to enable the email validationⓘ process to continue normally.

To delete any custom filter rule at the email, domain, mx or tld record level, you must enter the custom filter parameters using the endpoint to delete a filter rule.

Below is an example of how to delete a rule using the API. You must have a ZeroBounce account and access to your API key to delete a custom filter rule.

Please allow up to 1 minute for changes to propagate.

API DEFAULT URL: https://api.zerobounce.net/v2/filters/delete

API U.S.A. URL*: api-us.zerobounce.net/v2/filters/delete

API EU URL: api-eu.zerobounce.net/v2/filters/delete

Method: POST

Content-Type: application/x-www-form-urlencoded

*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.

Successful Response

  {"Message": "Filter successfully deleted"}

Unsuccessful Response

  {"Message": "Filter does not exist"}

Error Response

    {"Error": "Invalid API key or your account ran out of credits"}
    {"Error": "Missing param: api_key"}
    {"Error": "Missing param: rule"}
    {"Error": "Missing param: target"}
    {"Error": "Missing param: value"}
    {"Error": "Allowed values for rule: allow, block"}
    {"Error": "Allowed values for target: email, domain, mx, tld"}
    {"Error": "Bad email syntax for param: value"}
    {"Error": "Bad domain syntax for param: value"}
    {"Error": "Invalid request format"}

Code samples

List your filter results

After implementing your custom filter rules, the email validationⓘ API will automatically apply them to future validation attempts.

The validation process ends if it finds a matching “allow” or “block” rule for the email being validated. If you want an overview of your filters and the corresponding results, use the example below to get started.

This API shows you a complete list of your custom allow or block rules and all corresponding targets that match your rule set.

If at any point you need to add or delete new rules, you can do so at any time. Your changes will apply to future email validationⓘ attempts

If you need assistance implementing or deleting your custom allow or block rules, please contact our support team. We’re available 24/7 and ready to help you get your new allow and block lists prepared.

API DEFAULT URL: https://api.zerobounce.net/v2/filters/list

API U.S.A. URL*: api-us.zerobounce.net/v2/filters/list

API EU URL: api-eu.zerobounce.net/v2/filters/list

Method: GET

*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.

ENDPOINT RESPONSE

Successful Response

  [
    {
        "rule": "allow",
        "target": "email",
        "value": "test@example.com"
    },
    {
        "rule": "block",
        "target": "domain",
        "value": "example.com"
    },
    {
        "rule": "allow",
        "target": "mx",
        "value": "long.string.example.com"
    },
    {
        "rule": "allow",
        "target": "mx",
        "value": "*example.com"
    },
    {
        "rule": "allow",
        "target": "tld",
        "value": ".com"
    }
 ]

Error Response

  {"Error": "Invalid API key or your account ran out of credits"}
  {"Error": "Missing param: api_key"}

Code samples