Skip to main content
The official mailkube Node SDK covers the whole send surface with zero runtime dependencies. It ships ESM and CommonJS, is written in TypeScript, and requires Node 22.12+. It uses web standards only (fetch, AbortSignal, crypto.subtle) and no Node built-ins, so one build runs unchanged on Node, Cloudflare Workers, Deno, Bun, AWS Lambda and Cloud Functions. See Runtimes.

Install

npm

Get your API key

Create a key for a verified domain in the dashboard. The key is a string that starts with mk_. See Authentication for how to send it and keep it safe.

Send your first email

CommonJS callers, including n8n and Node-RED nodes, get the same surface:

Configure the client

Pass the key explicitly, or omit it and let the client read MAILKUBE_API_KEY:
Pass your own fetch to add instrumentation, a proxy agent, or a stub in tests:
If you are building something on top of this SDK, such as a CLI, an internal service, or a framework integration, set userAgentSuffix to your own name/version. It is appended after the SDK’s own token, so both are visible: mailkube-node/1.2.0 my-cli/1.0.0. The API requires a User-Agent on every request; the SDK already sends one, and this identifies your layer within it.
Your API key can send email on your behalf. Keep it server-side, injected from a secrets manager or environment variable. Never ship it in a browser bundle, a mobile app, or a public repository.

The response

A successful send returns two identifiers:
Use email.id to correlate the message with webhook events. Use email.messageId in In-Reply-To and References to thread replies.

Recipients, content and attachments

to, cc, bcc and replyTo each accept one address or an array. Supply html, text, or both. Attachment content takes raw bytes or an already base64-encoded string:
To send a saved template, pass templateId (and optional templateVersion) with a variables object, and leave html/text out. See Sending your first email for template behavior.

Idempotent sends

Pass idempotencyKey to anything you might retry. The API replays the original response on a retry, and idempotentReplayed tells you which happened:
The SDK does not retry on your behalf. See Idempotency.

Cancellation and timeouts

Every verb accepts an AbortSignal, merged with the client timeout so whichever fires first wins. On send it sits with the other parameters; on the scheduled-email verbs it is a second argument, where it can never be mistaken for a filter:

Scheduled sends

Add scheduledAt, an ISO-8601 string with an offset or a Date, and the send is accepted for later:

Managing what is scheduled

List one page, or walk every page lazily by following the links the server issues:
Pages are fetched only as you reach them; abandoning the loop early makes no further request. Whole batches move or cancel together:
An unknown batch is a no-op reporting 0, not an error. See Scheduled emails for horizons and listing windows.

Your API key

client.credential.info() returns the key the client authenticates with: its domain, organization, source-IP allowlist, plan and send-quota usage.
The key is checked exactly as a send checks it, so one call confirms a key works before your first send. A key that cannot send throws AuthenticationError with the error name invalid_api_key, and Checking a key lists the causes. Each call counts as a use of the key, and plan and quota figures can be up to 30 seconds old. plan is undefined when the organization has no subscription. A plan without a daily limit lists emails_per_month only, and remaining counts recipients, not messages. The call has a rate limit of its own for each key. The client keeps the key it was constructed with. To use another key, construct another client.

Handling errors

Every failure extends MailkubeError. Transport failures throw ConnectionError; the server’s status chooses the API error. Each carries errorName, message, statusCode, retryAfter and requestId.
The hierarchy under MailkubeError includes BadRequestError, AuthenticationError, NotFoundError, ConflictError, InvalidRequestError, RateLimitError, ServerError and ConnectionError. ErrorName lists every documented errorName as a constant, but the value stays a plain string. A name this release has never heard of is reported verbatim. See Errors. Quote requestId when reporting a failure to support.

Receiving webhooks

verify checks the signature over the raw request body and returns a typed event. It needs no client instance and no HTTP, and drops into any framework’s handler. It is async, because crypto.subtle is the only digest API every target runtime shares:
Verify against the raw received bytes. express.json() discards them, and re-serializing the parsed object changes the bytes, so the signature will not match. Use express.raw(), or new Uint8Array(await request.arrayBuffer()) on a Worker.
switch (event.type) narrows the payload, and event.data.bounce.reason is type-checked. Typed events exist for email.sent, email.delivered, email.bounced, email.delivery_delayed, email.suppressed, email.scheduled, email.failed, email.opened, email.clicked, domain.status and webhook.status. Anything newer arrives as type: "unknown" with the server’s own type on eventType, instead of throwing. event.raw always holds the whole decoded payload. A receiver that logs or forwards events never loses a field. X-Webhook-Id is stable across retries. Deduplicate on it before acting. See Webhooks for the full event catalog.

Signing, for your tests

Production code verifies; it never signs. sign is the other half, for building a request your handler will accept without waiting on a real delivery. Like verify, it is async:
It computes the HMAC exactly as verify checks it, so a fixture built this way cannot drift from the verifier. It takes the timestamp you give it and does not judge its freshness. Pass a stale one to assert that your handler rejects a replay.

Runtimes

One build runs everywhere as published. Every runtime below is exercised in CI against the published package. On Workers the key arrives per request through the env binding rather than from an ambient environment, so build the client inside the handler:
On Lambda and Cloud Functions the environment is ordinary and the container is reused, so build the client once at module scope instead.

Logging

Silent by default. Pass any logger, or set MAILKUBE_LOG to a level:
MAILKUBE_LOG holds a level, not a flag, so MAILKUBE_LOG=warning suppresses the SDK’s request and response records. The Authorization and Idempotency-Key headers are always masked, and message bodies are never logged.

Next steps

Scheduled emails

Scheduling horizons, listing windows, and the batch behavior behind scheduledAt and batchId.

Webhooks

Every event type that can reach verify, and the signing scheme it checks.

API reference

The wire-level fields, error codes, and rate limits behind emails.send.

Errors

What each ErrorName constant means and how to react.