Email Types

These types are exported from hono-email/adapter and re-exported from each adapter entry point.

---

EmailMessage

A fully rendered email message passed to an adapter.

type EmailMessage = {
  from: EmailAddress
  to: EmailAddress | EmailAddress[]
  cc?: EmailAddress | EmailAddress[]
  bcc?: EmailAddress | EmailAddress[]
  replyTo?: EmailAddress | EmailAddress[]
  subject: string
  html: string
  text: string
  attachments?: EmailAttachment[]
  headers?: Record<string, string>
  messageId?: string
  date?: Date
  envelope?: EmailEnvelope
  dkim?: EmailDkimOptions
}

from Required

Visible sender address. See EmailAddress.

to Required

Visible recipient address or addresses.

subject Required

Message subject line.

html Required

Rendered HTML body. Set automatically by sendEmail().

text Required

Plain-text body. Set automatically by sendEmail().

cc Optional

Carbon-copy addresses.

bcc Optional

Blind carbon-copy addresses.

replyTo Optional

Reply-to address or addresses.

attachments Optional

Message attachments. See EmailAttachment.

headers Optional

Custom email headers as a Record<string, string>.

messageId Optional

Custom Message-ID header value.

date Optional

Message date.

envelope Optional

SMTP envelope override. See EmailEnvelope.

dkim Optional

DKIM signing options. See EmailDkimOptions.

---

EmailMessageDraft

Email message with JSX instead of rendered html/text. Pass to sendEmail().

type EmailMessageDraft = Omit<EmailMessage, 'html' | 'text'> & {
  jsx: Child
  render?: RenderOptions
}

jsx Required

Email JSX tree. Rendered to html and text by sendEmail().

render Optional

Render options applied before delivery. See RenderOptions.

---

SendEmailOptions

Options for sendEmail(): all EmailMessageDraft fields plus an adapter.

type SendEmailOptions = EmailMessageDraft & {
  adapter: EmailAdapter
}

adapter Required

Delivery adapter (e.g. ResendAdapter(...), SmtpTransport, CloudflareEmailAdapter(...)).

---

SendEmailReceipt

Union of SuccessfulSendReceipt | FailedSendReceipt.

type SuccessfulSendReceipt = {
  successful: true
  messageId: string
  accepted: string[]
  rejected: string[]
  response: string
  queued?: boolean
  queuedRecipients?: string[]
}

type FailedSendReceipt = {
  successful: false
  accepted: string[]
  rejected: string[]
  errorMessages: string[]
  response?: string
  cause?: unknown
}

Narrow on receipt.successful to access success or failure fields:

const receipt = await sendEmail({ ... })
if (!receipt.successful) {
  console.error(receipt.errorMessages)
}

---

EmailAddress

type EmailAddress = string | { address: string; name?: string }

Pass a plain string or an object with address and an optional display name.

---

EmailAttachment

type EmailAttachment = {
  filename?: string
  content?: string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>
  path?: string
  href?: string
  contentType?: string
  contentDisposition?: 'attachment' | 'inline'
  cid?: string
  encoding?: 'base64' | 'hex' | 'utf8'
  headers?: Record<string, string>
}

filename Optional

Attachment filename shown to recipients.

content Optional

In-memory attachment content. One of content, path, or href is required.

path Optional

Remote URL or data URI to resolve as attachment content. Local files must be read by user code and passed as content.

href Optional

Remote URL to fetch as attachment content.

contentType Optional

MIME content type.

contentDisposition Optional

'attachment' (default) or 'inline'.

cid Optional

Content ID for inline attachments referenced in HTML as cid:....

encoding Optional

Encoding for string content: 'base64' | 'hex' | 'utf8'.

---

EmailEnvelope

SMTP envelope override. Useful when the envelope sender differs from the visible From address (e.g. for bounce handling).

type EmailEnvelope = {
  from?: EmailAddress
  to?: EmailAddress | EmailAddress[]
  cc?: EmailAddress | EmailAddress[]
  bcc?: EmailAddress | EmailAddress[]
}

---

EmailDkimOptions

DKIM signing options. Applied by the SMTP adapter and any adapter that supports DKIM.

type EmailDkimOptions = {
  domainName: string
  keySelector: string
  privateKey: string
  headerFieldNames?: string[]
  skipFields?: string[]
}

domainName Required

Signing domain (e.g. 'example.com').

keySelector Required

DKIM selector (e.g. 'mail').

privateKey Required

PEM private key string.

headerFieldNames Optional

Header names to include in the signature.

skipFields Optional

Header names to exclude from signing.

---

EmailAdapter

The interface implemented by all delivery adapters.

type EmailAdapter = {
  send(message: EmailMessage): Promise<SendEmailReceipt>
}

Pass a custom implementation when no built-in adapter fits your provider.