API reference

Send an email

Send a single email — transactional or one-off — through the API. The message is accepted and queued for delivery.

POST https://app.blacklistguard.com/api/v1/emails/send

Authenticate with your X-API-Key header and send a JSON body.

Request body

Field	Type	Required	Description
`to`	string	Yes	Recipient email address. A single recipient — one message per request.
`subject`	string	Yes	Subject line.
`body`	string	Yes	Message content. HTML and plain text are accepted — the format is detected automatically.
`from_email`	string	No	Sender address. Must be on a verified sending domain (or a verified sender). If omitted, the platform default sender is used.
`from_name`	string	No	Display name shown next to the sender address.
`bounce_email`	string	No	Address to route bounce notifications to.
`attachments`	array	No	File attachments — see below.

Attachment fields

Field	Required	Description
`filename`	Yes	File name shown to the recipient.
`content`	Yes	File contents, Base64-encoded.
`content_type`	Yes	MIME type, e.g. `application/pdf`.
`disposition`	No	`attachment` (default) or `inline` for embedded images.
`content_id`	No	For inline images — reference it in your HTML as `cid:<content_id>`.

ℹScope of this endpoint. It sends one message to one recipient. It does not support cc, bcc, reply-to, custom headers, scheduling, multiple recipients in one call, separate HTML/text parts, or templates. For audience sends, use campaigns.

Example request

curl -X POST https://app.blacklistguard.com/api/v1/emails/send \
  -H "X-API-Key: efk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "you@yourdomain.com",
    "from_name": "Acme",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "body": "<h1>Thanks!</h1><p>Your order is confirmed.</p>",
    "attachments": [
      { "filename": "receipt.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQK..." }
    ]
  }'

Response

A successful request returns 201 with the queued message's ID:

{
  "success": true,
  "data": { "status": "queued", "id": "1a3a56c6-4393-465e-86aa-d2c0d1200958" },
  "message": "Resource created successfully"
}

Use data.id to find the message in the console under Messages.

Errors

If the from_email isn't on a verified domain or sender, the request fails with 400 and code VALIDATION_ERROR, explaining that you need to verify the domain or sender first. See the error codes for the full list, including plan-limit and balance errors.