Sending Emails

Your app can send email through Hiveku in four ways:

The REST API, described on this page.
The Node.js SDK, @hiveku-apps/email, which sends single emails through the REST API. See Node.js SDK.
SMTP, for frameworks and services that send over SMTP. See SMTP.
The Resend-compatible API, for apps built on Resend. See Migrate from Resend.

All four run the same checks, count against the same limits, and show up in the same logs.

Authentication

Every request carries an API key as a Bearer token:

Authorization: Bearer hk_live_...

The base URL is https://app.hiveku.com/api/v1/email. Call it from your server, never from browser code, where anyone can copy the key.

Send an email

POST /api/v1/email/send sends one email. The key needs the Send Emails permission.

curl
Node.js
Node.js SDK

curl -X POST https://app.hiveku.com/api/v1/email/send \
  -H "Authorization: Bearer $HIVEKU_EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024-shipped" \
  -d '{
    "from": "Acme <noreply@mail.acme.com>",
    "to": ["customer@example.com"],
    "subject": "Your order #1024 has shipped",
    "html": "<h1>On the way</h1><p>Tracking: ABC123</p>",
    "text": "On the way. Tracking: ABC123",
    "tags": { "category": "orders", "order_id": "1024" }
  }'

const res = await fetch("https://app.hiveku.com/api/v1/email/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIVEKU_EMAIL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-shipped`,
  },
  body: JSON.stringify({
    from: "Acme <noreply@mail.acme.com>",
    to: ["customer@example.com"],
    subject: `Your order #${orderId} has shipped`,
    html: "<h1>On the way</h1><p>Tracking: ABC123</p>",
    text: "On the way. Tracking: ABC123",
    tags: { category: "orders", order_id: String(orderId) },
  }),
});

const result = await res.json();
if (!res.ok) throw new Error(`${res.status} ${result.code}: ${result.error}`);
console.log(result.id, result.status);

import { HivekuEmail } from "@hiveku-apps/email";

const email = new HivekuEmail(); // reads HIVEKU_EMAIL_API_KEY

const { id, status } = await email.send({
  from: "Acme <noreply@mail.acme.com>",
  to: "customer@example.com",
  subject: "Your order #1024 has shipped",
  html: "<h1>On the way</h1><p>Tracking: ABC123</p>",
  text: "On the way. Tracking: ABC123",
  tags: { category: "orders", order_id: "1024" },
});

A send answers 200 with the email’s id:

{
  "id": "5f0c7a2e-8d1b-4c3e-9a4f-2b6d8e1f0a37",
  "status": "sent",
  "message_id": "..."
}

Field	Meaning
`id`	Hiveku’s id for the email. Use it to look the email up, to find it in the logs, and to match webhook events (`data.email_id`).
`status`	`sent`: handed off for delivery. `simulated`: the key is not a production key, so nothing was delivered.
`message_id`	The id in the email’s `Message-ID` header. Only on a `sent` email.
`mode`, `message`	On a simulated send: `"mode": "test"` and a sentence saying nothing was delivered.
`warnings`	What Hiveku left out, such as a header it does not deliver or a reserved tag. Only present when there is something to say.
`suppressed_recipients`	Recipients left out because they are on the suppression list. The email still went to the others.

sent means Hiveku handed the email off, not that it arrived. Delivery, bounces and opens arrive later as webhook events, and in Settings > Email Service > Email Logs.

Node.js SDK

The @hiveku-apps/email package sends email through the REST API. Use its send() for single emails, through POST /api/v1/email/send. It needs Node.js 18 or later.

npm install @hiveku-apps/email

import { HivekuEmail, HivekuEmailError } from "@hiveku-apps/email";

// Reads HIVEKU_EMAIL_API_KEY, or pass the key: new HivekuEmail({ apiKey: "hk_live_..." })
const email = new HivekuEmail();

try {
  const { id, status } = await email.send({
    from: "Acme <noreply@mail.acme.com>",
    to: "customer@example.com",
    replyTo: "support@acme.com",
    subject: "Your invoice",
    html: "<p>Your invoice is attached.</p>",
    text: "Your invoice is attached.",
    attachments: [{ filename: "invoice.pdf", content: pdf.toString("base64"), contentType: "application/pdf" }],
  });
  console.log(id, status); // "sent", or "simulated" with a test key
} catch (error) {
  if (error instanceof HivekuEmailError) console.error(error.status, error.code, error.message);
  throw error;
}

send() takes from, to, subject, html, text, replyTo, cc, bcc, headers, tags and attachments. cc and bcc are lists, and content is the file as base64 text.
It answers what the REST API answers: id, status and the other fields above.
A refusal throws a HivekuEmailError. Its status is the HTTP status, code the error code, and message the sentence. On a billing block (402), version 1.0.1 puts a code such as account_past_due in message. See Errors.
The SDK sets no Idempotency-Key. For safe retries, batches, templates and lookups, call the REST API. The SDK’s sendBatch() takes at most 50 emails, and version 1.0.1 reads the batch answer under the wrong name, so send batches through the REST API.
scheduledAt schedules the email, as scheduled_at does (see Fields).

Fields

string | object

required

The sender: "Acme <noreply@mail.acme.com>", "noreply@mail.acme.com", or { "email": "noreply@mail.acme.com", "name": "Acme" }. The address must be on one of your verified domains, and on the key’s allowed domains if it has any.

string | string[]

required

One address or a list. A list may also hold { "email": "..." } objects. A name such as "Jane <jane@example.com>" is accepted, but only the address is kept.

string | string[]

Copy recipients.

string | string[]

Hidden recipients.

string

required

The subject line.

string

The HTML body. Send html, text, or both. At least one is required.

string

The plain-text body. Sending it along with html helps delivery.

string | string[]

Where replies go. replyTo works too. An entry that is not an email address is left out and named in warnings. At most 50.

object

Your own headers, as name to value. Only some are delivered. See Headers.

object | array

Labels that travel with the email. See Tags.

array

Files to attach. See Attachments.

string

The same as the Idempotency-Key header, for clients that cannot set headers. See Idempotency.

string | number

When to send it, up to 29 days ahead: an ISO 8601 date and time such as 2026-11-03T09:00:00Z, milliseconds since 1970, or "in 30 min" (minutes, hours or days). A time now or in the past, give or take a minute, sends at once.

The email is stored as scheduled, and the answer gives its id, status: "scheduled" and scheduled_at.
At its time Hiveku checks the key, the account, the sender’s domain, the suppression list, your plan and the key’s own daily limit again, then sends it. An email not sent within 15 minutes of its time fails as schedule_missed and is never sent late.
Scheduling counts against the key’s rate like a send now. An account can have as many scheduled emails waiting as its plan sends in a month; past that, 429 scheduled_limit_reached.
An email whose key is paused or deleted by its time fails and is not sent. So does one that would pass the key’s own daily limit: it fails as key_daily_limit_reached.
A batch cannot schedule.

An email can have at most 50 recipients, counting to, cc and bcc together.

Headers

Hiveku sets From, To, Cc, Reply-To and Subject from the fields above. Of your own headers, it delivers these:

List-Unsubscribe and List-Unsubscribe-Post, for one-click unsubscribe
List-Id
In-Reply-To and References, for threading
Auto-Submitted and Precedence
any X- header, except reserved ones such as X-Hiveku-

Each value must fit on one line, at most 870 characters. Only X- headers may hold text that is not plain ASCII. At most 15 headers are delivered. Anything else is dropped and named in warnings, and the email still goes.

"headers": {
  "List-Unsubscribe": "<https://acme.com/unsub?u=42>, <mailto:unsub@acme.com>",
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  "X-Entity-Ref-ID": "order-1024"
}

Attachments

"attachments": [
  {
    "filename": "invoice-1024.pdf",
    "content": "JVBERi0xLjQK...",
    "content_type": "application/pdf"
  }
]

content is the file as base64 text. A Node.js Buffer sent as JSON works too.
content_type is optional. Without it, the type comes from the file name.
content_id makes an inline image: refer to it as cid: plus the id in your HTML.
contentType and contentId work as names too.
path, a URL for Hiveku to fetch, is refused with 422 attachment_path_not_supported. Send the file itself.
Up to 100 files and 25 MB in all. The whole email may be at most 40 MB as sent. Larger emails are refused with 413.
A batch takes no attachments. Send those emails one at a time.
An attached web page that asks for a password, or sends the reader to another address as it opens, is refused with 403 attachment_blocked.

Hiveku keeps each file’s name, type and size in the logs, never the file.

Idempotency

Send an Idempotency-Key header to make retries safe. Use a value that names the email, such as order-1024-shipped, from 1 to 256 characters.

The same key with the same request within 24 hours answers with the first email (id, status, message_id) and sends nothing again. status is that email’s status now.
The same key with a different request is refused with 409 invalid_idempotent_request.
While the first request is still being sent, a retry gets 409 concurrent_idempotent_requests. Try again shortly.
If the first request never recorded its result, a retry gets 409 idempotent_request_outcome_unknown with the email’s id. It may have been sent: look it up before you send again, or use a new key to send regardless.
A send that failed frees its key, so a retry sends.
Keys belong to one API key. Two API keys can use the same value without clashing.

Batch sending

POST /api/v1/email/batch sends up to 100 emails in one request. Each email takes the fields of a single send, except attachments and scheduled_at.

curl -X POST https://app.hiveku.com/api/v1/email/batch \
  -H "Authorization: Bearer $HIVEKU_EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      { "from": "noreply@mail.acme.com", "to": "alice@example.com", "subject": "Welcome, Alice", "html": "<p>Hi Alice</p>" },
      { "from": "noreply@mail.acme.com", "to": "bob@example.com", "subject": "Welcome, Bob", "html": "<p>Hi Bob</p>" }
    ]
  }'

{
  "object": "batch",
  "data": [
    { "id": "5f0c7a2e-8d1b-4c3e-9a4f-2b6d8e1f0a37", "status": "queued" },
    { "id": "c3a1d9e4-6b2f-4f8a-9d0e-7a5b3c1e2f48", "status": "failed", "error": "Domain example.org is not verified. Please verify the domain first." }
  ]
}

Each email is checked on its own. One that fails does not stop the others.
queued means stored and on its way. The answer comes before the emails go out, so follow each one in the logs or by webhook.
suppressed lists any recipients left out of an email.
With a key that is not a production key, "mode": "test" and a note say nothing was delivered.
The rate limit and the monthly emails count every recipient of every email. When either refuses, the whole batch is refused with 429, and nothing is sent.
One Idempotency-Key covers the whole batch. A retry answers with the first ids.

Send with a template

POST /api/v1/email/send-template sends a saved template, filled with your values.

curl -X POST https://app.hiveku.com/api/v1/email/send-template \
  -H "Authorization: Bearer $HIVEKU_EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "order-shipped",
    "to": "customer@example.com",
    "variables": { "customer_name": "Sam", "order": { "number": "1024" } }
  }'

template_id or template_name picks the template.
Placeholders such as {{customer_name}} and {{order.number}} in the template’s subject, HTML and text are replaced with your values. A placeholder with no value is left as it is.
from, subject and reply_to fall back to the template’s defaults when you leave them out.
cc, bcc, headers, tags and attachments work as on a single send.
A missing required variable is refused with 400 missing_variables, which lists them in missing. An unknown template answers 404 not_found.
The answer has the id, the template (id and name), from, to, subject, status and created_at.

In the HTML body, each value is HTML-escaped, so text your users typed shows as text. Write {{{name}}} (three braces) to insert a value as HTML, as it is. The subject and the plain text get values as typed.

Look up an email

GET /api/v1/email/emails/{id} returns one email: its addresses, subject, HTML and text, status, tags, timestamps (sent_at, delivered_at, opened_at and the rest), open and click counts, any error, and its event timeline.

The key needs the Read Emails permission. A send-only key gets 403 missing_permission.
A key reads only the emails it sent itself. Any other id answers 404.
Each read is written to the account’s audit log.
The HTML and text are removed 30 days after sending, and then come back as null.

POST /api/v1/email/emails/{id}/cancel cancels an email still waiting for its time (status scheduled). One already on its way or sent answers 400 invalid_status. Only the key that scheduled it can cancel it; any other answers 404.

Test keys

Only a production key delivers email. With any other key, Hiveku checks the email as usual (the key, the verified domain, the limits), records it with the status simulated, answers, and delivers nothing. Simulated emails do not count against your monthly emails. They show in the logs with the status Simulated, so you can open them and check how they rendered. See API keys.

Errors

/send answers an error as { "error": "<sentence>", "code": "<code>" }, plus any details. Batch, send-template and email lookups wrap it as { "error": { "message": "<sentence>", "code": "<code>" } }, and answer a bad key with 401 unauthorized, and a key used from an address it does not allow with 403 ip_not_allowed. The codes below are the ones /send uses.

Status	Code	When
`400`	`invalid_request`	The body is not JSON.
`400`	`validation_error`	A field is missing or wrong. The sentence says which.
`400`	`all_recipients_suppressed`	Every recipient is on the suppression list. `suppressed_recipients` lists them.
`401`	`invalid_api_key`	The key is missing, wrong, paused or deleted.
`402`		Billing blocks sending. `message` says what to do.
`403`	`permission_denied`	The key lacks the Send Emails permission.
`403`	`ip_not_allowed`	The key has allowed addresses and the call came from another address. The sentence names the key and the address.
`429`	`scheduled_limit_reached`	The account already has as many scheduled emails waiting as its plan sends in a month.
`403`	`domain_not_verified`	The `from` domain is not a verified domain of the account.
`403`	`domain_not_allowed`	The key may not send from that domain.
`403`	`account_suspended`, `email_sending_disabled`	Sending is switched off for the account.
`403`	`content_blocked`, `attachment_blocked`, `bounce_rate_exceeded` and others	Hiveku’s abuse checks refused the email.
`409`	`invalid_idempotent_request`, `concurrent_idempotent_requests`, `idempotent_request_outcome_unknown`	See Idempotency.
`413`	`attachments_too_large`, `message_too_large`	Over 25 MB of attachments, or over 40 MB as sent.
`422`	`attachment_path_not_supported`	An attachment has a `path` instead of `content`.
`429`	`rate_limit_exceeded`	The key’s rate. One batch larger than a minute at the key’s own limit is refused whole, with no `Retry-After`: split it. See Limits.
`429`	`key_daily_limit_reached`	The key’s own daily limit. It sends again from 00:00 UTC. See Limits.
`429`	`email_limit_reached`	The month’s emails are used up. `limit` and `current` say how many.
`429`	`velocity_spike`	The daily volume check holds API mail until 00:00 UTC.
`500`		The email was stored but could not be sent. `id` names it.

A 429 carries a Retry-After header and a retry_after field in seconds when waiting helps.

Logs

Every email shows up in Settings > Email Service > Email Logs. The App sends (API and SMTP) view lists the email your apps sent. The log keeps the message itself (its text and HTML) for 30 days after you send it, then removes it. Who it went to, the subject, the status, and the opens, clicks and bounces stay. This applies to every way of sending: the REST API, the SDK, the Resend-compatible API and SMTP. Opening an email’s content needs the Open sent emails permission, which owners and admins have.

Get Started

Dashboards

AI Assistant

Code Editor

Design Studio

CMS

Email Marketing

Social Media

Advertising

Marketing Delivery

Commerce

Calendar

Communications

Helpdesk

Sales

Publishing

Native Mobile

Email

Integrations

How-Tos

Account & Settings

Partners

Authentication

Send an email

Node.js SDK

Fields

Headers

Tags

Attachments

Idempotency

Batch sending

Send with a template

Look up an email

Test keys

Errors

Logs

​Authentication

​Send an email

​Node.js SDK

​Fields

​Headers

​Tags

​Attachments

​Idempotency

​Batch sending

​Send with a template

​Look up an email

​Test keys

​Errors

​Logs

Authentication

Send an email

Node.js SDK

Fields

Headers

Tags

Attachments

Idempotency

Batch sending

Send with a template

Look up an email

Test keys

Errors

Logs