Blacklist

Beeving never sends to a blacklisted email address. The blacklist is shared across the platform: an address blacklisted after a bounce or complaint is protected for everyone. Each workspace sees and manages only the entries it added.

The entry object

{
  "id": 9,
  "email": "bounce@example.com",
  "reason": "bounce",
  "created_at": "2026-02-01T10:00:00.000000Z"
}

reason is one of bounce, complaint, manual or unsubscribe. Emails are stored in lowercase.

Endpoints

Method	Path	Permission	Description
GET	/blacklist	blacklist:read	Entries your workspace added (paginated). Query: search
POST	/blacklist	blacklist:write	Add an email
GET	/blacklist/reasons	blacklist:read	The available reasons and their labels
POST	/blacklist/check	blacklist:read	Check whether an email is blacklisted
POST	/blacklist/bulk-create	blacklist:write	Add up to 1000 emails
DELETE	/blacklist/bulk-delete	blacklist:write	Remove up to 1000 emails
GET	/blacklist/{id}	blacklist:read	Get an entry
DELETE	/blacklist/{email}	blacklist:write	Remove an email. Returns 204.

List blacklist entries

GET /blacklist returns entries added by the authenticated token's workspace. Platform-wide entries and entries from other workspaces are not exposed.

Parameter	Type	Default	Description
page	integer	1	Page number, starting at 1
per_page	integer	15	Results per page, from 1 to 100
search	string		Partial email address
reason	string		bounce, complaint, manual or unsubscribe
sort	string	created_at	email, reason or created_at
direction	string	desc	asc or desc

GET /api/v1/blacklist?search=example.com&reason=bounce&sort=email&direction=asc&page=2

The response follows the pagination contract. Equal sort values are ordered consistently by entry ID.

Add an email

{ "email": "someone@example.com", "reason": "manual" }

201: { "data": Entry }. If the email is already blacklisted, you get 422 with "Email is already blacklisted".

Check an email

POST /blacklist/check

This endpoint has its own limit of 30 requests per minute.

{ "email": "someone@example.com" }

{
  "data": {
    "email": "someone@example.com",
    "is_blacklisted": true,
    "reason": "manual",
    "blacklisted_at": "2026-02-01T10:00:00.000000Z"
  }
}

reason and blacklisted_at are filled in only when your workspace added the entry.

Bulk add / remove

{ "emails": ["a@example.com", "b@example.com"], "reason": "manual" }

reason is only needed for bulk add.

• Bulk add returns 201: { "data": { "added": 1, "skipped": 1 } }. skipped counts emails that were already blacklisted.
• Bulk remove returns 200: { "data": { "deleted": 2, "not_found": 0 } }.