email.onUnsubscribed

The recipient opted out — mirror it into your own preferences.

Fires when the recipient opts out through an unsubscribe link, their mail client’s one-click header, or a reply that reads as an opt-out. The provider already stops the next send; this hook keeps your own preference UI in sync, so someone who unsubscribed by email doesn’t see themselves still subscribed in your app.

hooks: {
  email: {
    onUnsubscribed: async (event) => {
      await prisma.emailPreference.upsert({
        where: {
          email_list: { email: event.recipient, list: event.listId ?? "*" },
        },
        create: { email: event.recipient, list: event.listId ?? "*", subscribed: false },
        update: { subscribed: false },
      });
    },
  },
},

listId is set when the provider names the list they left. Without it the opt-out isn’t tied to a list — usually all non-transactional mail, not necessarily every email. AIInbx says which: getAIInbxOutbound(event)?.unsubscribeScope is "all" or "optional". Resend, Mailgun, and AIInbx emit this event.

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"
    | "unsubscribed"

Event status/type

Type

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

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

provider?Record<string, unknown>

Provider-specific typed extras, namespaced by provider (e.g. `provider.aiinbx` — read it with `getAIInbxOutbound(event)`).

TypeRecord<string, unknown>

raw?unknown

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

Typeunknown

listId?string

Unsubscribe list the recipient opted out of, when the provider names one. Absent means not list-specific, which is not necessarily every email.

Typestring

source?"link" | "one_click" | "reply" | (string & {})

How the recipient opted out

Type"link" | "one_click" | "reply" | (string & {})