Sending Emails

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"]
  }'

Response:

{
  "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`

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

Email parameters

string | string[]

required

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

string

required

Sender address. Must be on a verified domain. Supports friendly format: Acme <noreply@mail.acme.com>.

string

required

Email subject line.

string

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

string

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

string | string[]

CC recipients.

string | string[]

BCC recipients.

string | string[]

Reply-To address(es).

Attachment[]

File attachments. See Attachments below.

string[]

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

Record<string, string>

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

string

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

Record<string, unknown>

Variable values for the template.

string (ISO 8601)

Schedule the send for a future time.

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: "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);
}

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: "noreply@mail.acme.com",
  to: "customer@example.com",
  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: "noreply@mail.acme.com",
  to: "customer@example.com",
  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: "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",
    },
  ],
});

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: "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",
  },
});

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: "noreply@mail.acme.com",
  to: "customer@example.com",
  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.

Get Started

AI Assistant

Code Editor

Design Studio

CMS

Email Marketing

Social Media

Advertising

Commerce

Calendar

Communications

Sales

Publishing

Native Mobile

Email

Integrations

How-Tos

Account & Settings

Partners

Choose an integration

Email parameters

Batch sending

Template sending

Scheduled delivery

Attachments

Custom headers

Tracking tags

Idempotency

Response format

​Choose an integration

​Email parameters

​Batch sending

​Template sending

​Scheduled delivery

​Attachments

​Custom headers

​Tracking tags

​Idempotency

​Response format

Choose an integration

Email parameters

Batch sending

Template sending

Scheduled delivery

Attachments

Custom headers

Tracking tags

Idempotency

Response format