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. The key needs the emails:send permission.

Request body

A request without from_email, to or subject is rejected with a 400 and nothing is queued. Fields the endpoint does not know are ignored.

Choosing the sending IP

Leave virtual_mta_ip out and the message uses your default: your own dedicated IP if you have one, otherwise BlacklistGuard's shared pool. Set it to choose where the message is sent from instead. It takes the same values as the campaign field of the same name:

• An empty string, or no field at all, for your default.
• "shared_pool" to always use the shared pool, even if you have a dedicated IP.
• An IP address, such as "203.0.113.10". It must be one of your own verified dedicated IPs, including any you've bought from us. You'll find them under Virtual MTAs in the console.
• "routing_rule:<id>" to send through one of your active routing rules.

Your choice is kept with the message, so it still applies if the message has to wait in the queue. If the IP stops being yours before the message goes out, for example because you released a dedicated IP, it uses your default instead.

Attachment fields

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, or through the reporting API.

A message to an address your workspace has suppressed is accepted like any other, but it isn't delivered. Its status becomes skipped, with the reason address is suppressed.

A 201 means the message is queued, not delivered. The platform makes one delivery attempt. A message that fails is not sent again automatically, so check its status and send it again from your side if you need to.

Errors

See the error codes for the full list, including plan-limit and balance errors.