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 withmk_. See Authentication for how to send it and keep it safe.
Send your first email
Configure the client
Pass the key explicitly, or omit it and let the client readMAILKUBE_API_KEY:
Pass your own
fetch to add instrumentation, a proxy agent, or a stub in tests:
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.
The response
A successful send returns two identifiers: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
PassidempotencyKey to anything you might retry. The API replays the original response on a retry, and idempotentReplayed tells you which happened:
Cancellation and timeouts
Every verb accepts anAbortSignal, 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
AddscheduledAt, an ISO-8601 string with an offset or a Date, and the send is accepted for later:
Managing what is scheduled
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.
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 extendsMailkubeError. Transport failures throw ConnectionError; the server’s status chooses the API error. Each carries errorName, message, statusCode, retryAfter and requestId.
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:
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:
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:
Logging
Silent by default. Pass any logger, or setMAILKUBE_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.