API reference — BlacklistGuard Docs

API reference

The BlacklistGuard HTTP API lets you send email and manage your audience, sending domains, and reporting programmatically. Every endpoint speaks JSON and uses the conventions on this page.

Base URL

All API requests go to:

https://app.blacklistguard.com/api/v1

Authentication

Authenticate every request with an API key in the X-API-Key header. Keys begin with efk_ and are tied to your workspace.

curl https://app.blacklistguard.com/api/v1/emails/send \
  -H "X-API-Key: efk_your_api_key"

See Authentication & API keys for creating, rotating, and securing keys.

Response format

Responses use a consistent envelope. On success, your data is in data:

{ "success": true, "data": { /* ... */ }, "message": "..." }

On failure, success is false and you get an error message plus a machine-readable code:

{ "success": false, "error": "From address is not authorized", "code": "VALIDATION_ERROR" }

Error codes

The HTTP status reflects the outcome; the code field tells you exactly what happened. The codes you're most likely to handle:

Code	HTTP	Meaning
`VALIDATION_ERROR`	400	The request was malformed or a field was invalid.
`BAD_REQUEST`	400	The request couldn't be processed as sent.
`UNAUTHORIZED`	401	Missing or invalid API key.
`FORBIDDEN`	403	The key isn't allowed to perform this action.
`NOT_FOUND`	404	The requested resource doesn't exist.
`CONFLICT`	409	The request conflicts with existing data (e.g. a duplicate).
`RATE_LIMIT_EXCEEDED`	429	Too many requests too quickly — slow down and retry.
`PLAN_LIMIT_REACHED`	402	Your plan's monthly volume is used up.
`INSUFFICIENT_BALANCE`	402	Your prepaid balance is too low to cover this action.
`EMAIL_NOT_VERIFIED`	403	The sender address or domain isn't verified yet.
`SERVICE_SUSPENDED`	403	The workspace is suspended.
`INTERNAL_ERROR`	500	Something went wrong on our side — retry shortly.

Rate limits

The API accepts up to 100 requests per second (with short bursts to 200) per source IP. If you exceed that, requests return 429 with code RATE_LIMIT_EXCEEDED — pause briefly and retry. For steady throughput, keep well under the limit and add a small backoff when you see a 429.

Quotas & plan limits

How much you can send is governed by your plan, not a fixed request cap. Each plan includes a monthly email allowance:

Plan	Included emails / mo	Over the allowance
Free	3,000	Sending pauses when the allowance is reached.
Growth — $35/mo	50,000	$0.0008 per additional email.
Scale — $95/mo	250,000	$0.0008 per additional email.
Enterprise	Custom	Negotiated.

On paid plans, sending beyond your allowance draws from your prepaid balance — if it runs out, sends return INSUFFICIENT_BALANCE until you top up. Free plans hard-stop at the allowance with PLAN_LIMIT_REACHED. Your workspace may also have an optional hourly send cap configured by an administrator.

Pagination

List endpoints accept page and limit query parameters and return a pagination object alongside the results:

{
  "success": true,
  "data": {
    "pagination": { "page": 1, "limit": 50, "total": 214, "total_pages": 5 },
    "transactions": [ /* ... */ ]
  }
}

Endpoints

Reference pages by resource:

Send an email — POST /emails/send
Campaigns — list, send, pause, and report on campaigns
Mailing lists & subscribers — lists, subscribers, segments, custom fields
Suppression lists — block addresses from sending
Email validation — verify addresses before you send
Sending domains — add, verify, and manage domains
DKIM keys — generate and rotate signing keys
Reporting — stats, message log, deliverability, bounces & complaints
Blacklist checker — check IPs and domains, schedule monitors
API keys — create, rotate, and revoke keys
Billing — balance, subscription, usage, transactions