BulkMail API Docs

BulkMail provides an HTTP API for sending email. All requests and responses use JSON, so you can call it from any language.

Quick start

1. Sign up, then click the link in the verification email to verify your address.
2. Add your domain on the Domains page of the dashboard, then add the DNS records shown there at your DNS provider. Once the DKIM record is live, the domain switches to Verified automatically.
3. Create a key on the API Keys page. The key is shown only once, so store it safely.
4. Send your first email:

curl -X POST https://bulkmail.dev/emails \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>This is my first email</p>"
  }'

Authentication

Every API request must include your API key in a header:

Authorization: Bearer mk_your_api_key

An API key is as sensitive as your password. Use it only on the server, never in web or app frontend code. If one leaks, delete it in the dashboard and create a new one.

Send email

The email enters the send queue and the API returns its ID immediately. Get the delivery result from the retrieve endpoint or a webhook.

Request parameters

The total of to, cc and bcc recipients can’t exceed your plan’s limit (see Limits).

Response

HTTP/1.1 202 Accepted

{
  "id": "9db6562a-d026-4c68-ae7d-df08dd3af862",
  "status": "queued",
  "suppressed": []
}

suppressed lists recipients skipped because they’re on the suppression list. If every recipient is suppressed, status is suppressed and the email is not sent.

Email status

Retrieve email

Returns the email content, its current status, and delivery events for each recipient.

{
  "id": "9db6562a-d026-4c68-ae7d-df08dd3af862",
  "from": "Acme <hello@acme.com>",
  "to": ["user@example.com"],
  "subject": "Hello",
  "status": "delivered",
  "created_at": "2026-11-08T10:24:01.000Z",
  "sent_at": "2026-11-08T10:24:02.000Z",
  "events": [
    {
      "type": "delivered",
      "recipient": "user@example.com",
      "detail": "250 2.0.0 OK",
      "created_at": "2026-11-08T10:24:03.000Z"
    }
  ]
}

Lists emails, newest first. limit is at most 100. When next_before in the response is not empty, pass it as before to get the next page.

Domains

{ "name": "acme.com" }

Returns the domain and the DNS records to add:

Checks the DNS records right away. We also check automatically every 10 minutes. A domain not verified within 72 hours of being added expires and must be added again.

Webhook

{ "url": "https://your-app.com/webhooks/mail" }

The first time you set it, the response includes the signing secret, shown only this once. After that, every time an email’s status changes, we send a POST request to this URL:

{
  "type": "email.delivered",
  "created_at": "2026-11-08T10:24:03.000Z",
  "data": {
    "email_id": "9db6562a-d026-4c68-ae7d-df08dd3af862",
    "recipient": "user@example.com",
    "detail": "250 2.0.0 OK"
  }
}

Event types

Any 2xx response from your server counts as success. Otherwise we retry with exponential backoff, up to 8 times.

Verifying signatures

Each request carries two headers: X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature. Compute an HMAC-SHA256 of timestamp + "." + raw body with your signing secret and compare it with the signature:

import crypto from "node:crypto";

export function verifyWebhook(headers, rawBody, secret) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"] ?? "";
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  // Reject requests older than 5 minutes to prevent replays
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh
    && sig.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Error codes

On error, the response body is { "error": "description" }.

Limits and pricing

Quota counts recipients (one email to 3 people counts as 3). The daily quota resets at 00:00 UTC and the monthly quota on the 1st of each month. Overage is billed monthly. To upgrade, submit a request on the Plans page of the dashboard.

Bounce and complaint rates are measured over the last 7 days. Accounts above the threshold are suspended automatically, to protect deliverability for everyone on the platform.