Sending Emails

Send transactional emails via SDK, REST API, or SMTP

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)

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 <[e-mail]>",
  to: "[e-mail]",
  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"],
});

REST API

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 <[e-mail]>",
    "to": "[e-mail]",
    "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"]
  }'

Response:

{
  "messageId": "msg_01HPQRS...",
  "status": "queued"
}

SMTP

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

SMTP sends inherit the same domain verification, rate limits, and scopes as the API key used as the password.

Email parameters

to · string | string[] · required

Recipient address(es). Pass a string for one recipient or an array for many.

from · string · required

Sender address. Must be on a verified domain. Supports friendly format: Acme <[e-mail]>.

subject · string · required

Email subject line.

html · string

HTML body. At least one of html or text is required.

text · string

Plain-text body. Strongly recommended alongside html for deliverability.

cc · string | string[]

CC recipients.

bcc · string | string[]

BCC recipients.

reply_to · string | string[]

Reply-To address(es).

attachments · Attachment[]

File attachments. See Attachments below.

tags · string[]

Tags for filtering analytics and webhooks. Up to 10 tags per email.

headers · Record<string, string>

Custom headers (e.g., List-Unsubscribe).

template_id · string

Send with a template instead of raw html/text. See Templates.

variables · Record<string, unknown>

Variable values for the template.

scheduled_at · string (ISO 8601)

Schedule the send for a future time.

idempotency_key · string

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: "[e-mail]",
    to: "[e-mail]",
    subject: "Welcome, Alice",
    html: "<p>Hi Alice!</p>",
  },
  {
    from: "[e-mail]",
    to: "[e-mail]",
    subject: "Welcome, Bob",
    html: "<p>Hi Bob!</p>",
  },
]);

for (const r of results) {
  console.log(r.messageId, r.status);
}

Each item in the batch is validated and enqueued independently — a failure on one item does not block the others.

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: "[e-mail]",
  to: "[e-mail]",
  variables: {
    customer_name: "Sam",
    order_number: "1024",
    tracking_url: "https://acme.com/track/ABC123",
  },
});

REST endpoint: 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: "[e-mail]",
  to: "[e-mail]",
  subject: "Your trial ends tomorrow",
  html: "<p>Reminder!</p>",
  scheduled_at: "2026-04-18T15:00:00Z",
});

Scheduled emails can be canceled before their delivery window opens.

Attachments

Attachments are passed as base64-encoded content:

await hiveku.emails.send({
  from: "[e-mail]",
  to: "[e-mail]",
  subject: "Your invoice",
  html: "<p>See attached.</p>",
  attachments: [
    {
      filename: "invoice-1024.pdf",
      content: pdfBuffer.toString("base64"),
      content_type: "application/pdf",
    },
  ],
});

Total message size (including all attachments) is capped at 40 MB.

Custom headers

Pass arbitrary headers via the headers field. Common uses:

await hiveku.emails.send({
  from: "[e-mail]",
  to: "[e-mail]",
  subject: "This week at Acme",
  html: "<p>News!</p>",
  headers: {
    "List-Unsubscribe": "<https://acme.com/unsub?u=42>, <mailto:[e-mail]>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  },
});

Tracking tags

Tags flow through to analytics, webhooks, and suppression filters. Use them to slice sends by feature, tenant, or campaign:

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: "[e-mail]",
  to: "[e-mail]",
  subject: "Your order shipped",
  html: "<p>On the way!</p>",
});

Response format

All send endpoints return a consistent shape:

{
  "messageId": "msg_01HPQRS...",
  "status": "queued",
  "scheduled_at": null,
  "created_at": "2026-04-17T12:34:56Z"
}

Track the message further via Webhooks or the dashboard logs.