BlueyEmail API

Authentication

Every request needs an API key. Pass it as an X-API-Key header (recommended) or a Bearer token. Create keys in Settings → Integrations.

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Test the connection

Confirm a key works with a single call to GET /api/v2/me. It needs no scope and returns the workspace, the key’s auth context, and sending: whether you can send yet, your verified domains, and the exact next step if not — ideal for a platform’s “Test connection” step.

curl -X GET "https://api.blueyemail.com/api/v2/me" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "workspace": { "id": "uuid", "name": "Acme Inc" },
    "auth": { "method": "api_key", "mode": "live", "sandbox": false, "scopes": ["leads:write", "emails:send"] },
    "sending": { "ready_to_send": true, "verified_domains": ["acme.com"], "pending_domains": [], "next_step": "Ready. Send from any address on acme.com with POST /api/v2/transactional/send." }
  }
}

Quick start

Send your first transactional email in one request. It needs two things first: a sending domain verified in Settings → Sending Domains, and an API key with Read & write access. Every send needs a from address on that verified domain — we never choose one for you.

curl -X POST "https://api.blueyemail.com/api/v2/transactional/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "Your Name <hello@your-verified-domain.com>",
  "to": "you@example.com",
  "subject": "Hello from BlueyEmail",
  "html": "<h1>It works!</h1>"
}'

Sending over SMTP

BlueyEmail sends over HTTPS instead of SMTP. There is less to set up — no host, port, encryption mode or mail password — and it keeps working on hosting that blocks outbound SMTP ports, which is one of the most common reasons email quietly stops sending.

Here is how to connect, depending on what you are sending from:

Connecting something else, or a platform you would like us to support? Tell us what you are working with — it genuinely shapes what we build next.

Sending addresses

To send through the API you don’t need an email account. Put any address on a domain you have verified in from, for example "from": "Acme <hello@yourdomain.com>". Email accounts are the senders your campaigns use. There are three kinds, and the API can do different things with each:

Find an account’s id with GET /api/v2/email-accounts. Ids are UUIDs; words like platform are not ids. Updates use PATCH with only the fields you want to change.

Rate limits & sending volume

Two different limits apply, and it helps to keep them separate.

1 · API request rate

How many HTTP calls your workspace can make. Your allowance is set by your plan and is shared across every API key and OAuth token in the workspace — creating more keys does not raise it. Both a per-minute and a per-hour cap apply. Exceeding either returns 429 RATE_LIMITED. Every response carries your live budget in headers:

2 · Email sending volume

This is separate from the request rate. How many emails you can actually send is governed by a daily sending limit (small for brand-new workspaces, rising automatically — see Sending limits) and your monthly plan limit. A send over a limit is refused with 429 and a retry_at time — it is not queued, so retry after that time.

Sending limits

Paid plans get their full limits from day one. On the free plan or a trial, a new workspace sending through BlueyEmail starts with a small daily allowance that rises on its own as the account ages. You don’t need to do anything.

Days are counted in UTC, so the daily count also resets at 00:00 UTC. An hourly limit protects against sudden spikes. When a limit is reached, nothing is sent and nothing is queued. You get 429 with a code of DAILY_SEND_LIMIT or HOURLY_SEND_LIMIT, the exact time you can send again in retry_at, and the same wait in seconds in the Retry-After header. Retry after that time.

Check where you are

GET /api/v2/me (and GET /api/v2/emails/stats) return a sending_limits object: today’s daily_limit (limit, used, remaining, when it resets and when it rises) and the hourly_limit. While a daily limit applies, every send response also carries X-Daily-Send-Limit, X-Daily-Send-Remaining and X-Daily-Send-Reset, so your code can slow down before it is refused. The workspace owner and admins are also emailed the first time a daily limit is reached each day.

The hourly limit: while the daily limit is 1,000 or less, the whole day may be sent in one hour. Above that, the hourly limit is one-twelfth of the daily one (for example, a free plan’s 2,000 a day allows about 167 an hour).

Your plan’s own limits apply on top, at all times: API Free 100 a day and 50 an hour, API Essentials 10,000 a day and 2,000 an hour, API Pro 20,000 and 4,000, API Premier 200,000 and 20,000. These are rolling windows (any 24 hours, any hour), shown under sending_limits.plan.usage. Going over one also returns 429 with retry_at.

{
  "error": {
    "type": "rate_limit_error",
    "code": "DAILY_SEND_LIMIT",
    "reason": "new_account_ramp",
    "retry_at": "2026-10-07T00:00:00.000Z",
    "message": "New account: 50 emails/day for first 24 hours. ... Nothing was sent. You can send again at 2026-10-07T00:00:00Z (in about 59 minutes)."
  }
}

Errors

Errors return a nested error object with a type (derived from the HTTP status), a human-readable message, and a machine-readable code. The HTTP status is on the response itself. Some endpoints add extra fields (e.g. limit, reset_at, or the required scopes).

{
  "error": {
    "type": "auth_error",
    "message": "Invalid API key",
    "code": "INVALID_API_KEY"
  }
}

Common codes and what to do