@hiveku-apps/email

Official Node.js / TypeScript SDK for the Hiveku Transactional Email Service.

Send transactional emails, manage sending domains and read delivery stats through one API.

Installation

npm install @hiveku-apps/email

Quick start

import HivekuEmail from '@hiveku-apps/email';

const email = new HivekuEmail('hk_live_YOUR_KEY');

await email.send({
  from: 'Acme <[email protected]>',
  to: '[email protected]',
  subject: 'Welcome to Acme!',
  html: '<p>Thanks for signing up.</p>',
});

Or set HIVEKU_EMAIL_API_KEY in your environment and call the module-level helper:

import { sendEmail } from '@hiveku-apps/email';

await sendEmail({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello World',
  html: '<p>Welcome!</p>',
});

Usage with curl

curl -X POST https://app.hiveku.com/api/v1/email/send \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to Acme!",
    "html": "<p>Thanks for signing up.</p>"
  }'

API

new HivekuEmail(apiKeyOrConfig?)

| Parameter | Type | Description | |-----------|------|-------------| | apiKey | string | Your Hiveku API key (hk_live_... or hk_test_...) | | baseUrl | string | Override the API base URL | | timeout | number | Request timeout in ms (default: 30000) |

Methods

| Method | Description | |--------|-------------| | send(options) | Send a single email | | sendBatch(emails[]) | Send up to 50 emails in one request; data lists each one | | listDomains() | List all sending domains | | addDomain(domain) | Add a domain and get DNS records | | verifyDomain(domainId) | Re-check domain DNS verification | | deleteDomain(domainId) | Remove a domain | | getUsage(options?) | Get delivery stats | | generateSmtpCredentials() | Generate SMTP credentials |

send(options) options

| Field | Type | Required | Description | |-------|------|----------|-------------| | from | string | ✓ | Sender: "Name <email>" or a plain address | | to | string \| string[] | ✓ | Recipient(s) | | subject | string | ✓ | Subject line | | html | string | | HTML body | | text | string | | Plain-text body | | replyTo | string | | Reply-to address | | cc | string[] | | CC recipients | | bcc | string[] | | BCC recipients | | headers | Record<string,string> | | Custom headers | | tags | Record<string,string> | | Tracking tags | | attachments | Attachment[] | | File attachments (base64) | | scheduledAt | string | | Schedule delivery (ISO 8601) |

Answers

send() answers { id, status }. The status is sent for a production key, such as hk_live_..., or simulated for any other key, such as hk_test_...: the email is recorded and nothing is delivered.

sendBatch() answers { data }, one entry per email in the order sent: { id, status }, where the status is queued, failed (with error saying why) or unknown (with note saying what to do). results is the same list, the name 1.0.1 used.

const { data } = await email.sendBatch([first, second]);
for (const sent of data) console.log(sent.id, sent.status);

Errors

A failed request throws a HivekuEmailError with the HTTP status, the API's code and message, and the rest of the error in details (such as retry_after, in seconds, when sending is paused).

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

try {
  await email.send({ from, to, subject, html });
} catch (err) {
  if (err instanceof HivekuEmailError) {
    console.error(err.status, err.code, err.message, err.details);
  }
}

Environment variables

| Variable | Description | |----------|-------------| | HIVEKU_EMAIL_API_KEY | API key used by the default client | | HIVEKU_API_URL | Override the API base URL |

Changelog

See CHANGELOG.md.

Links

• Dashboard: app.hiveku.com
• API Docs: app.hiveku.com/docs
• Status: status.hiveku.com

License

MIT