Add to Block ListBeta

Block one email address or domain.

POSThttps://api.foxreach.io/api/v1/block-list

Requires an API key with the write scope.

The value is lowercased and classified: anything with an @ is an email, anything else a domain. @acme.com, *.acme.com and https://acme.com/page are all stored as the domain acme.com. For many values at once use Bulk Add.

Body Parameters#

valuestringbodyrequired

An email address or a domain.

notestringbody

Optional note, up to 500 characters.

Response#

Returns the entry with a 201 status code.

dataobject

Show data

idstring

Entry identifier.

kindstring

email or domain.

valuestring

Lowercased address or domain.

sourcestring

manual, import, unsubscribe or api.

notestring

Optional note, or null.

createdBystring

User id that added it, or null for unsubscribes.

createdAtstring

ISO 8601 timestamp.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`409`	`Already on the block list.`
`422`	`value` is missing or not a valid email or domain

Rate Limit#

120 requests per minute, shared by every write call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (write).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Request

cURL

curl -X POST "https://api.foxreach.io/api/v1/block-list" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"value": "acme.com", "note": "Asked us to stop"}'

Python SDK (beta)

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
entry = client.block_list.add("acme.com", note="Asked us to stop")

TypeScript SDK (beta)

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const entry = await client.blockList.add({ value: "acme.com", note: "Asked us to stop" });

Response

JSON

{
  "data": {
    "id": "blk_abc123",
    "kind": "domain",
    "value": "acme.com",
    "source": "api",
    "note": "Asked us to stop",
    "createdBy": "usr_abc123",
    "createdAt": "2026-11-04T10:00:00Z"
  }
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026