Client API

The emailkit client options, methods, message types, results, and errors.

This page lists the full client API. For a guided setup, start with the Quickstart.

Set up emailkit

import { EmailKit } from "emailkit";

const emailkit = EmailKit({
  emailDrivers: [driver],
  hooks,
  secret,
  publicRoutes,
  resolveEmailDriver,
});

Option	Required	Purpose
`emailDrivers`	✓	One or more configured providers
`hooks`	—	Handles email events and connects mailbox, domain, and webhook changes to your app
`secret`	For OAuth drivers	Signs callback state; defaults to `EMAILKIT_SECRET`
`publicRoutes`	—	Public origin and route templates; `PUBLIC_BASE_URL` supplies the default origin
`resolveEmailDriver`	With multiple drivers	Selects a provider and loads mailbox login details from your storage

emailkit does not persist these values itself. Resolvers load state from your database; mailbox, domain, and webhook hooks tell your app when that state changes.

Core methods

API	Purpose
`sendEmail(message, options?)`	Send through a selected driver
`handler()`	Create the framework-agnostic webhook and callback handler
`getDriver(id)`	Access the configured driver instance
`attachments.getContent(attachment)`	Retrieve inline or provider-stored content
`providerFetch(path, init?)`	Call a provider-only endpoint with the saved login details

Domain, mailbox, and webhook methods

Methods appear only when one of your configured providers supports them.

Facade	Methods
`domains`	`list`, `create`, `get`, `getOrNull`, `ensure`, `update`, `verify`, `delete`, `remove`, `webhooks`, `sync`
`mailboxes`	`connect`, `create`, `list`, `get`, `delete`, `webhooks`, `sync`
`webhooks`	account-level `setup`, `refresh`, `delete`
root client	account-level `sync`

Message types

Every provider shares the base message. TypeScript adds more fields when your selected provider supports them.

PropType

fromEmailAddress

TypeEmailAddress

toEmailAddress | EmailAddress[]

TypeEmailAddress | EmailAddress[]

subjectstring

Typestring

text?string

Typestring

html?string

Typestring

provider?Record<string, unknown>

Provider-specific options (escape hatch)

TypeRecord<string, unknown>

Common optional fields include cc, bcc, reply, attachments, headers, tags, metadata, templateId, templateData, sendAt, track, sandbox, idempotencyKey, and tenantId.

Send result

PropType

messageIdstring

Typestring

providerstring

Typestring

threadId?string

Provider/native thread identifier, when returned by the driver.

Typestring

requestId?string

Request identifier for tracing (if provided by driver)

Typestring

providerId?string

Provider-specific email identifier (in addition to messageId). This is the provider's internal ID for this email, separate from the RFC Message-ID. Useful for provider-specific operations or tracking.

Typestring

replyThreading?"applied" | "skipped"

How `reply.messageId` threading was honored by drivers with the `nativeReplyThreading` capability. - "applied": the provider created a native reply to `reply.messageId`, so the outgoing message carries proper reply headers and threading. - "skipped": `reply.messageId` was provided but the source message was not found in the mailbox; the message was sent unthreaded. Absent for drivers that emit RFC reply headers directly (the `replyHeaders` capability) and for sends without `reply.messageId`.

Type"applied" | "skipped"

accepted?string[]

Typestring[]

rejected?string[]

Typestring[]

Attachments

PropType

emailDriver?string

EmailKit driver id that owns this attachment. Inbound webhook attachments are stamped by the EmailKit client so `emailkit.attachments.getContent(attachment)` can self-route later.

Typestring

filenamestring

Filename of the attachment

Typestring

content?string | Uint8Array

Attachment content (Uint8Array for binary, string for text). Present when attachment is sent directly in webhook body.

Typestring | Uint8Array

url?string

URL to fetch the attachment content (requires authentication with provider). Present when attachment is stored separately by the provider.

Typestring

contentType?string

MIME content type (e.g., "image/png", "application/pdf")

Typestring

size?number

Size of the attachment in bytes

Typenumber

contentId?string

Content-ID (CID) for inline attachments referenced in HTML. This is the value used in HTML to reference the attachment (e.g., "ii_mheuh73y1"). In HTML, it's referenced as `cid:ii_mheuh73y1` or `<img src="cid:ii_mheuh73y1">`. Only present for inline attachments (when `isInline` is true).

Typestring

isInline?boolean

Whether this attachment is referenced inline in the HTML body. - `true`: Attachment is embedded in HTML (e.g., `<img src="cid:...">`) - `false` or `undefined`: Regular attachment (not inline) When `true`, you should replace `cid:${contentId}` references in the HTML with the actual attachment URL or a proxied version.

Typeboolean

provider?Record<string, unknown>

Provider-specific metadata needed for later attachment retrieval.

TypeRecord<string, unknown>

Errors

EmailKitError gives every provider error the same fields: provider, code, httpStatus, cause, and the original provider data. EmailKitSyncError also tells you how many recovered events were handled and where a failed sync can continue.

try {
  await emailkit.sendEmail(message);
} catch (error) {
  if (error instanceof EmailKitError) {
    logger.error({
      provider: error.provider,
      code: error.code,
      status: error.httpStatus,
    });
  }
}