email.onComplained

The recipient marked a message as spam — stop emailing them.

Fires when the recipient reports a message as spam through their mail provider’s feedback loop. Treat it as a hard unsubscribe: keep sending after a complaint and your sender reputation pays for it.

hooks: {
  email: {
    onComplained: async (event) => {
      await prisma.suppression.upsert({
        where: { email: event.recipient },
        create: { email: event.recipient, reason: "complaint" },
        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

feedbackType?string

Type of complaint (spam, abuse, etc.)

Typestring

feedback?string

Feedback loop message

Typestring

source?string

Complaint source (ESP, ISP, etc.)

Typestring