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/nodeWorks 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.