API reference

BlueyEmail API

Send transactional email, manage contacts, run campaigns, and receive HMAC-signed webhooks — a single REST API over 132 JSON endpoints.

v2 APIREST · JSONHMAC webhooks1k–10k req/hr

Base URL  https://api.blueyemail.com

Building a connector? Download the OpenAPI spec to auto-generate one. Public, no auth required.

Open in dashboard to run live requests Signed in, your key fills in automatically — never paste a secret key on a public page.

Explore the 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 → API keys.

X-API-Key header
X-API-Key: YOUR_API_KEY
Authorization: Bearer
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"
Response
{
  "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>"
}'

The API sends transactional email — receipts, OTPs, notifications — via /api/v2/transactional/send. For marketing (newsletters, campaigns), don't send per-recipient: (POST /api/v2/campaigns/:id/leads) so unsubscribes, warmup, and segments are respected.

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:

Your own code or appAvailable now

Send with the REST API — one POST with your API key. Attachments, scheduling, custom headers and Reply-To are all supported. See Quick Start above to send your first email in a couple of minutes.

WordPress or WooCommerceIn development

We are building an official BlueyEmail plugin so you can skip SMTP entirely. Install it, paste your API key, and every email your site sends goes through BlueyEmail — WooCommerce orders and invoices, password resets, contact form replies. Nothing else to configure.

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:

Kind (provider)Add itChange through the APIRemove it
BlueyEmail sending address (platform_smtp)Dashboard: Settings → Email accountsdisplay_name, is_active, purposeDashboard
Your own SMTP server (custom_smtp)POST /api/v2/email-accounts/smtpEverything, including SMTP settingsDELETE /api/v2/email-accounts/:id
Gmail / Outlook (gmail, outlook, …)Dashboard: sign in with Google/Microsoftdisplay_name, is_active, purposeDashboard

Find an account’s id with . 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:

PlanRequests / minuteRequests / hour
Free301,000
Spark1205,000
Grow30020,000
Business60050,000
API Free603,000
API Essentials30030,000
API Pro600150,000
API Premier1,200500,000
X-RateLimit-Limit1000Requests allowed this hour
X-RateLimit-Remaining842Requests left this hour
X-RateLimit-Reset1710415260Unix time the window resets
Retry-After42Seconds to wait (on 429)

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 to thousands? You don't make one call per recipient. Use (POST /api/v2/transactional/batch) — up to 1,000 messages per request. So 5,000 emails is just 5 API calls, far inside any rate limit. The single-send endpoint also accepts up to 50 recipients per call.

Sending limits

Every plan has a few simple sending limits. On Free, a trial or API Free, a brand-new workspace can send up to 50 emails through BlueyEmail (the API and BlueyEmail sending addresses) in its first 24 hours, then its plan’s numbers apply; paid plans get theirs from day one.

PlanA dayAn hourA month
Free250No separate cap500
Free trial (any plan)15050Daily limit only; lifted when the trial converts
Spark, Grow, BusinessNo daily capAbout 4,200, pacedThe volume you bought
API Free10050500
API Essentials10% of your monthly volume (10,000 at 100,000)2% of your monthly volume (2,000 at 100,000)The volume you bought
API Pro20% of your monthly volume (20,000 at 100,000)4% of your monthly volume (4,000 at 100,000)The volume you bought
API Premier200,00020,000The volume you bought

The workspace’s daily count resets at midnight in your workspace’s timezone, and reaching a limit never blocks your account: we email you that day, and again when it resets. On Free and trials, the daily limit counts campaign email from every sending account, your own Gmail, Outlook or SMTP included, and everything sent through BlueyEmail’s API and sending addresses. On an API plan, the day and hour count every API send. When a limit is reached, nothing is sent and nothing is queued. You get 429 with a code of DAILY_SEND_LIMIT, HOURLY_SEND_LIMIT or MONTHLY_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.

New sending accounts start small

Every sending account you add (a Gmail, Outlook or SMTP mailbox, or your BlueyEmail sending address) also starts small, on every plan including paid ones, and rises by itself, counted from when the account was added: up to 50 emails on its first day, then 100 a day to the end of day 3, 250 to day 7, 500 to day 14, 1,000 to day 21 and 2,000 to day 30. This applies to campaigns, automations, and email sent through Zapier; sends through the transactional API (/transactional/send and /transactional/batch) are not affected. After day 30 the ramp ends, and the account’s own daily limit and your plan’s limits still apply. If you turn on warm-up for an account, its warm-up schedule is used instead. This per-account count resets at midnight UTC.

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), the hourly_limit, and your plan’s usage under sending_limits.plan.usage. 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 get one email on a day a limit is reached, listing every limit hit, and another when the daily limit resets.

429 — daily limit reached
{
  "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 response
{
  "error": {
    "type": "auth_error",
    "message": "Invalid API key",
    "code": "INVALID_API_KEY"
  }
}
400validation_errorInvalid or missing parameters
401auth_errorInvalid or missing API key
403permission_errorAPI key lacks the required scope, or this sender cannot send
404not_found_errorResource or endpoint does not exist
405invalid_request_errorRight path, wrong method — see the Allow header
409conflict_errorConflict with current state (e.g. duplicate idempotency key, a form still used by a landing page)
422invalid_request_errorRequest understood but refused (e.g. a suppressed recipient)
429rate_limit_errorRequest rate or sending limit reached — check Retry-After
500api_errorServer error — retry with backoff

Common codes and what to do

VALIDATION_ERRORSomething in the request is missing or malformed — the message names it. Invalid JSON is usually a shell line-break inside -d.
ENDPOINT_NOT_FOUNDNo such endpoint. The message suggests the right one when it can.
METHOD_NOT_ALLOWEDUse a method from the Allow header (updates are PATCH, not PUT).
FIELD_NOT_EDITABLEThat field can’t be changed on this account; editable_fields lists what can.
MANAGED_IN_DASHBOARDThis account is managed in Settings → Email accounts.
SENDER_REQUIRED / DOMAIN_NOT_VERIFIEDSend from an address on a domain you have verified.
DAILY_SEND_LIMIT / HOURLY_SEND_LIMITNothing was sent. Retry at retry_at (see Sending limits).
RECIPIENT_SUPPRESSEDOne of your own contacts bounced or complained before; remove it from your list.
RECIPIENT_UNAVAILABLEWe can’t send to this address right now; nothing was sent. No further detail is available.
STAFF_PAUSEDBlueyEmail review paused this campaign (409 on start, resume and schedule); only our team can resume it. Contact support.
SENDER_NOT_ALLOWEDThis sender address or workspace can’t send right now; the message says why.
MONTHLY_SEND_LIMITYour plan’s monthly emails are used. Nothing was sent; the count resets on the 1st of each month (00:00 UTC), or upgrade.
CONTENT_BLOCKEDOur safety checks flagged the content (phishing-style wording, a suspicious link, or scripted HTML). The message names the specific finding when there is one. Nothing was sent; change the content and send again. Campaign start, schedule and resume return 422 with validation_errors and blocked_emails.
MISSING_POSTAL_ADDRESS422. Marketing email (a marketing send through the API or Zapier) needs your business postal address. Add it in Settings → Workspace and send again. Transactional email is not affected.
TRACKING_DOMAINS_DISABLED409. Custom tracking domains are switched off for now; links are tracked through our own HTTPS domain. Existing links keep working.
FORM_USED_BY_LANDING_PAGE409 on DELETE /forms/:id. The form belongs to a landing page; delete that landing page first.
IDEMPOTENCY_IN_PROGRESSA request with the same idempotency key is still running. Wait a moment and retry with the same key.
IDEMPOTENCY_KEY_REUSED422. This idempotency_key was already used for a different request body, so nothing was sent. Use a new key for a different email; reuse a key only to retry the exact same request.
SEND_BLOCKEDStopped by our safety checks. Contact support with the request time if it looks wrong.