email.onBounced

A message could not be delivered — suppress hard bounces before they hurt your sender reputation.

Fires when a message could not be delivered. severity separates hard from soft: permanent means the address is dead — stop sending to it; temporary means the recipient’s server may accept it later. reason, smtpResponse, and code carry the provider’s explanation.

hooks: {
  email: {
    onBounced: async (event) => {
      if (event.severity !== "permanent") return;
      await prisma.suppression.upsert({
        where: { email: event.recipient },
        create: { email: event.recipient },
        update: {},
      });
    },
  },
},

Payload

PropType

emailDriver?string

EmailKit driver id that produced this event, attached by the EmailKit client.

Typestring

schemaVersion?"1"

Schema version for forward-compat

Type"1"

eventId?string

Unique event identifier for dedupe

Typestring

messageIdstring

Unique message identifier from the email provider

Typestring

providerId?string

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

Typestring

recipientstring

Email address of the recipient (always available)

Typestring

status

| "sent"
    | "delivered"
    | "opened"
    | "clicked"
    | "bounced"
    | "complained"
    | "rejected"

Event status/type

Type

| "sent"
    | "delivered"
    | "opened"
    | "clicked"
    | "bounced"
    | "complained"
    | "rejected"

timestampDate

Timestamp when the event occurred

TypeDate

from?EmailAddress

Sender email address (available in sent/accepted events)

TypeEmailAddress

to?EmailAddress[]

Recipient email addresses (available in sent/accepted events)

TypeEmailAddress[]

subject?string

Email subject (available in sent/accepted events)

Typestring

tags?EmailTag[]

Custom metadata/tags associated with the email

TypeEmailTag[]

metadata?Record<string, string>

Custom metadata key-value pairs

TypeRecord<string, string>

campaignId?string

Campaign or tracking identifier

Typestring

recipientDomain?string

Domain of the recipient (e.g., "gmail.com")

Typestring

server?string

Receiving server information

Typestring

raw?unknown

Provider-specific raw data (for debugging or advanced use cases)

Typeunknown

reason?string

Human-readable bounce reason/message

Typestring

severity?"permanent" | "temporary"

Bounce severity: permanent (hard bounce) or temporary (soft bounce)

Type"permanent" | "temporary"

code?string | number

Error code from the email provider

Typestring | number

smtpResponse?string

SMTP response code and message

Typestring

category?string

Bounce category/type

Typestring