email.onRejected

The provider refused to send — blocked address, policy, or suppression list.

Fires when the provider refuses to send at all — a blocked address, a policy violation, or a recipient already on the provider’s suppression list. Unlike a bounce, the message never left; reason and category say why.

hooks: {
  email: {
    onRejected: async (event) => {
      await prisma.sentEmail.updateMany({
        where: { messageId: event.messageId },
        data: { status: "rejected", error: event.reason },
      });
    },
  },
},

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 rejection reason

Typestring

code?string | number

Error code from the email provider

Typestring | number

smtpResponse?string

SMTP response code and message

Typestring

category?string

Rejection category/type

Typestring