Skip to content

Search documentation

Search pages and sections

Integrations

Node.js SDK

The official TypeScript SDK for Node.js 18+: send emails, manage templates and suppressions, and verify webhooks.

Install

npm install @hulakimail/node

Works in Node.js 18.17+, Bun and Deno. The client reads HULAKIMAIL_API_KEY from the environment when no key is passed.

Send an email

import { HulakiMail } from '@hulakimail/node';

const hulakimail = new HulakiMail(process.env.HULAKIMAIL_API_KEY);

const { id, status } = await hulakimail.emails.send(
  {
    from: 'Acme <[email protected]>',
    to: '[email protected]',
    template_id: 'tpl_01JD3R2K6Q8W4M1T7Z9X5B3N0C',
    variables: { first_name: 'Ada', order: { number: '#4821' } },
    tags: ['receipt'],
    attachments: [{ filename: 'invoice.pdf', content: pdfBuffer }], // Buffers are base64-encoded for you
  },
  { idempotencyKey: `receipt-${order.id}` },
);

Other resources

await hulakimail.emails.batch([email1, email2]);          // up to 100
const email = await hulakimail.emails.get('msg_01JD…');
await hulakimail.emails.cancel('msg_01JD…');             // scheduled emails only

for await (const e of hulakimail.emails.listAll({ status: 'bounced' })) {
  console.log(e.to, e.status);
}

await hulakimail.templates.create({ name: 'Welcome', subject: 'Hi {{first_name}}', html: '…' });
await hulakimail.suppressions.create({ email: '[email protected]' });
const domain = await hulakimail.domains.get('acme.com');

Errors & retries

Failed requests throw a subclass of HulakiMailError with status, type, code and param. Rate-limited and server errors are retried automatically with backoff; sends always carry an idempotency key so retries are safe.

import { HulakiMailError, RateLimitError, ValidationError } from '@hulakimail/node';

try {
  await hulakimail.emails.send(params);
} catch (err) {
  if (err instanceof ValidationError) console.error(err.code, err.param, err.message);
  else if (err instanceof RateLimitError) console.error('retry after', err.retryAfter);
  else if (err instanceof HulakiMailError) console.error(err.status, err.type);
  else throw err;
}

Webhooks

// Next.js route handler: app/api/webhooks/hulakimail/route.ts
import { HulakiMail } from '@hulakimail/node';

export async function POST(req: Request) {
  const body = await req.text(); // raw body
  try {
    const event = HulakiMail.webhooks.verify(body, req.headers.get('HulakiMail-Signature'), process.env.HULAKIMAIL_WEBHOOK_SECRET!);
    if (event.type === 'email.bounced') {
      // mark the address as undeliverable …
    }
    return new Response(null, { status: 200 });
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }
}

Something unclear or missing? Tell us.