Hiveku offers three ways to send email. Use the SDK when you can, fall back to REST when you cannot, and use SMTP when you need to plug Hiveku into a third-party service that only speaks SMTP (Supabase Auth, Firebase Auth, WordPress, etc.).
Choose an integration
SDK (recommended)
REST API
SMTP
The @hiveku-apps/email SDK handles authentication, retries, rate-limit backoff, and typed responses.npm install @hiveku-apps/email
import { Hiveku } from "@hiveku-apps/email";
const hiveku = new Hiveku({ apiKey: process.env.HIVEKU_API_KEY! });
const { messageId } = await hiveku.emails.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: ["order-shipped", "tenant-42"],
});
POST to /v1/email/send with a Bearer token.curl -X POST https://api.hiveku.com/v1/email/send \
-H "Authorization: Bearer hk_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-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": ["order-shipped", "tenant-42"]
}'
{
"messageId": "msg_01HPQRS...",
"status": "queued"
}
Use SMTP for third-party services that cannot call an HTTP API (Supabase Auth, Firebase Auth, WordPress, Rails ActionMailer, Django EMAIL_BACKEND, etc.).| Setting | Value |
|---|
| Host | smtp.hiveku.com |
| Port | 465 (SSL) or 587 / 2587 (STARTTLS) |
| Username | apikey |
| Password | Your hk_live_... or hk_test_... key |
| Auth | PLAIN or LOGIN |
Email parameters
to
string | string[]
required
Recipient address(es). Pass a string for one recipient or an array for many.
Sender address. Must be on a verified domain. Supports friendly format: Acme <noreply@mail.acme.com>.
HTML body. At least one of html or text is required.
Plain-text body. Strongly recommended alongside html for deliverability.
Tags for filtering analytics and webhooks. Up to 10 tags per email.
Custom headers (e.g., List-Unsubscribe).
Send with a template instead of raw html/text. See Templates. Variable values for the template.
Schedule the send for a future time.
Client-generated key to prevent duplicate sends on retry.
Batch sending
Send up to 100 emails in a single request with POST /v1/email/batch:
const { results } = await hiveku.emails.batch([
{
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>",
},
]);
for (const r of results) {
console.log(r.messageId, r.status);
}
Template sending
If you have a saved template, reference it by ID and pass variables:
await hiveku.emails.sendTemplate({
template_id: "tmpl_order_shipped",
from: "noreply@mail.acme.com",
to: "customer@example.com",
variables: {
customer_name: "Sam",
order_number: "1024",
tracking_url: "https://acme.com/track/ABC123",
},
});
POST /v1/email/send-template.
Scheduled delivery
Schedule a send for a future time by passing an ISO 8601 scheduled_at:
await hiveku.emails.send({
from: "noreply@mail.acme.com",
to: "customer@example.com",
subject: "Your trial ends tomorrow",
html: "<p>Reminder!</p>",
scheduled_at: "2026-04-18T15:00:00Z",
});
Attachments
Attachments are passed as base64-encoded content:
await hiveku.emails.send({
from: "noreply@mail.acme.com",
to: "customer@example.com",
subject: "Your invoice",
html: "<p>See attached.</p>",
attachments: [
{
filename: "invoice-1024.pdf",
content: pdfBuffer.toString("base64"),
content_type: "application/pdf",
},
],
});
headers field. Common uses:
await hiveku.emails.send({
from: "newsletter@mail.acme.com",
to: "subscriber@example.com",
subject: "This week at Acme",
html: "<p>News!</p>",
headers: {
"List-Unsubscribe": "<https://acme.com/unsub?u=42>, <mailto:unsub@acme.com>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
},
});
tags: ["password-reset", "tenant-42", "experiment-b"];
Idempotency
Pass an idempotency_key to make retries safe. If Hiveku receives the same key twice within 24 hours, the second request returns the original response without sending again.
await hiveku.emails.send({
idempotency_key: `order-${orderId}-shipped`,
from: "noreply@mail.acme.com",
to: "customer@example.com",
subject: "Your order shipped",
html: "<p>On the way!</p>",
});
{
"messageId": "msg_01HPQRS...",
"status": "queued",
"scheduled_at": null,
"created_at": "2026-04-17T12:34:56Z"
}
