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_email is required", "code": "BAD_REQUEST" }

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.
`INSUFFICIENT_SCOPE`	403	The key's permissions don't cover this endpoint. The response lists the missing ones in `required_scopes`. See Permissions.
`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, or you've reached your hourly, daily or monthly sending limit. The message says which. Slow down and retry, or wait for the limit to reset.
`FEATURE_NOT_AVAILABLE`	403	Your plan doesn't include this feature. An API key gets this on every request when the plan has no API access.
`PLAN_LIMIT_REACHED`	402	You've reached a limit of your plan, such as the monthly volume or the number of a resource you can create.
`INSUFFICIENT_BALANCE`	402	Your prepaid balance is too low to cover this action.
`EMAIL_NOT_VERIFIED`	403	The account's own email address hasn't been verified yet. Returned when signing in to the console, not for an unverified sender, which is a `BAD_REQUEST`.
`PAYMENT_FAILED`	402	A new plan or an upgrade couldn't be paid from your balance or saved payment method. Nothing changed.
`PAYMENT_PROCESSING`	409	A plan change is still waiting on its payment. Try again once it has settled.
`SERVICE_SUSPENDED`	402	Your subscription is suspended because a payment is overdue. Pay what's due under Billing and service resumes automatically.
`SENDING_PAUSED`	403	Sending is paused for your account because of its sending reputation, so nothing was sent. Contact support to have it reviewed.
`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.

Plans can also cap how many emails you send in a day. On Free it's 100. Days run on UTC, so the count resets at 00:00 UTC. Once you reach the cap, Send an email returns 429 with RATE_LIMIT_EXCEEDED, and mail already queued waits until the next day. A campaign with more recipients than you have left for the day isn't sent: it goes back to draft, and your workspace admins get an email about it.

Your plan also sets how many users your workspace can have. Adding one past that returns 402 with PLAN_LIMIT_REACHED. You can check both, along with your other plan limits, with GET /billing/limits.

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, dedicated IPs, transactions