Configuration

These throw a plain Error from the line that had the wrong value in it, rather than surfacing as a confusing failure on your first send. The message says what was wrong and what to pass instead.

Build the client once and share it. A fresh instance per request throws away the fetch binding and the configuration for nothing, and none of the state on it is per-caller.

For the case that would otherwise force one instance per key, such as a job sending on behalf of several workspaces, pass apiKey on the call. It replaces the Authorization header for that request and leaves nothing behind on the client.

await nextmail.emails.send(message) await nextmail.emails.send(message, { apiKey: workspace.apiKey }) await nextmail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await nextmail.webhooks.list({ apiKey: workspace.apiKey })

Every method outside tempMail takes it in its last argument, beside signal, and on a list that is the same object as the filters. It is checked before the request is sent, by the same rule the constructor uses, so a typo throws an Error naming { apiKey } on this call rather than a 401 about a credential you then have to go and find. A retried call keeps the key it was given.

signal is an AbortSignal. Aborting it stops the request, and any retry waiting behind it.

The client refuses to start in a browser and throws before any request goes out. A key in a page is a key you have published: it can send mail and read the mailbox for anyone who opens devtools. Call it from a server, a serverless function or a script instead.

Disposable inboxes are the exception. createTempMail() builds a client that carries no API key, so it is safe in a page. It creates inboxes anonymously, and each read sends the inbox token that create returned, or the newer one extend returned, either per call as inboxToken or once as createTempMail({ inboxToken }).

import { createTempMail } from '@nextmail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })

An app a person connected over OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as accessToken, either the token itself, or a function that returns it or a promise of it. The function is called once for every call, and that call’s retries reuse what it returned, so renew the token inside it when it is close to expiring and the client never has to be rebuilt.

import { Nextmail } from '@nextmail/sdk' export const nextmail = new Nextmail({  accessToken: async () => session.freshAccessToken(),}) const me = await nextmail.me.get() if (me.object === 'oauth_token') console.log(me.clientId, me.expiresAt)

Before a sensitive change, such as deleting a domain or changing a webhook, the API asks an access token for the verification code the web app would ask the person for. The call throws an NextmailApiError whose isStepUpRequired is true, and nothing was changed. Ask for a code, verify the one the person gives you, then make the call again. An API key is never asked.

import { NextmailApiError, nextmail } from '@nextmail/sdk' try {  await nextmail.domains.delete(domain.id)} catch (error) {  if (!(error instanceof NextmailApiError) || !error.isStepUpRequired) throw error   const challenge = await nextmail.security.beginStepUp()   const code = await ask(    challenge.method === 'email'      ? `Enter the code we emailed to ${challenge.sentTo}`      : 'Enter the code from your authenticator app, or a backup code',  )   await nextmail.security.verifyStepUp({ code })  await nextmail.domains.delete(domain.id)}