Email & webhook providers

npm install @notifykitjs/resend

import { resendProvider } from "@notifykitjs/resend"

export const notify = createNotifyKit({
  // ...
  providers: {
    email: resendProvider({
      apiKey: process.env.RESEND_API_KEY!,
      from: process.env.RESEND_FROM!,   // "App <noreply@app.com>"
      replyTo: "support@app.com",       // optional
    }),
  },
})

import type { EmailProvider } from "@notifykitjs/core"

export function postmarkProvider(opts: {
  token: string
  from: string
}): EmailProvider {
  return {
    id: "postmark",
    async send(input) {
      const res = await fetch("https://api.postmarkapp.com/email", {
        method: "POST",
        headers: {
          "Accept": "application/json",
          "Content-Type": "application/json",
          "X-Postmark-Server-Token": opts.token,
        },
        body: JSON.stringify({
          From: opts.from,
          To: input.to,
          Subject: input.subject,
          TextBody: input.body,
        }),
      })
      if (!res.ok) throw new Error(`Postmark: ${res.status}`)
      const json = await res.json() as { MessageID: string }
      return { providerMessageId: json.MessageID }
    },
  }
}

import { webhookProvider } from "@notifykitjs/core"

createNotifyKit({
  // ...
  providers: {
    webhook: webhookProvider({
      secret: process.env.WEBHOOK_SIGNING_SECRET,
    }),
  },
})

import { verifyWebhookSignature } from "@notifykitjs/core"

app.post("/webhooks/notifykit", (req, res) => {
  const signature = req.headers["x-notifykit-signature"]
  const valid = verifyWebhookSignature(req.rawBody, signature, SECRET)
  if (!valid) return res.status(401).end()
  // process the notification...
})

import type { SmsProvider } from "@notifykitjs/core"

export function twilioProvider(opts: {
  accountSid: string
  authToken: string
  from: string
}): SmsProvider {
  return {
    id: "twilio",
    async send(input) {
      const res = await fetch(
        `https://api.twilio.com/2010-04-01/Accounts/${opts.accountSid}/Messages.json`,
        {
          method: "POST",
          headers: {
            Authorization: `Basic ${btoa(`${opts.accountSid}:${opts.authToken}`)}`,
            "Content-Type": "application/x-www-form-urlencoded",
          },
          body: new URLSearchParams({
            From: opts.from,
            To: input.to,
            Body: input.body,
          }),
        },
      )
      if (!res.ok) throw new Error(`Twilio: ${res.status}`)
      const json = await res.json() as { sid: string }
      return { providerMessageId: json.sid }
    },
  }
}

// Run: npx tsx scripts/test-provider.ts
import { postmarkProvider } from "./lib/providers/postmark"

const provider = postmarkProvider({
  token: process.env.POSTMARK_TOKEN!,
  from: "test@yourapp.com",
})

const result = await provider.send({
  to: "your-own-email@gmail.com",
  subject: "[TEST] NotifyKit provider smoke test",
  body: "If you see this, the provider works.",
})

console.log("✓ Sent:", result.providerMessageId ?? "(no message ID returned)")

import type { Queue } from "@notifykitjs/core"

const bullQueue: Queue = {
  async enqueue(job) {
    await queue.add("notifykit", job, { jobId: job.deliveryId })
  },
  async drain() {
    await queue.drain()
  },
}

import { Queue as BullQueue } from "bullmq"
import type { Queue as NotifyKitQueue } from "@notifykitjs/core"

const connection = { host: process.env.REDIS_HOST!, port: 6379 }

const deliveryQueue = new BullQueue("notifykit-deliveries", {
  connection,
  defaultJobOptions: {
    removeOnComplete: 1000,  // keep last 1000 completed jobs for debugging
    removeOnFail: 5000,      // keep last 5000 failed for investigation
  },
})

export const bullMQQueue: NotifyKitQueue = {
  async enqueue(job) {
    await deliveryQueue.add("deliver", job, {
      jobId: job.deliveryId, // prevents duplicate jobs on retry
    })
  },
  async drain() {
    await deliveryQueue.close()
  },
}

import { Worker } from "bullmq"
import { notify } from "./lib/notifykit"

const connection = { host: process.env.REDIS_HOST!, port: 6379 }

const worker = new Worker(
  "notifykit-deliveries",
  async (job) => {
    await notify.processDeliveryJob(job.data)
  },
  {
    connection,
    concurrency: 10,           // parallel deliveries
    limiter: { max: 50, duration: 1000 }, // 50 jobs/sec max
  },
)

worker.on("failed", (job, err) => {
  console.error(`Delivery ${job?.id} failed: ${err.message}`)
})

// Graceful shutdown
process.on("SIGTERM", async () => {
  await worker.close()
  process.exit(0)
})

createNotifyKit({
  // ...
  retry: {
    maxAttempts: 5,
    delayMs: (attempt) => Math.min(1000 * 2 ** (attempt - 1), 30_000),
  },
})

import type { EmailProvider } from "@notifykitjs/core"

export function myProvider(opts): EmailProvider {
  return {
    id: "my-esp",
    async send(input) {
      const res = await fetch("https://api.provider.com/send", {
        method: "POST",
        headers: { Authorization: `Bearer ${opts.apiKey}` },
        body: JSON.stringify({ to: input.to, subject: input.subject, body: input.body }),
      })

      if (res.ok) {
        const json = await res.json()
        return { providerMessageId: json.id }
      }

      // Permanent errors — retrying won't help
      if (res.status === 400 || res.status === 422) {
        const err = new Error(`Provider rejected: ${res.status}`)
        ;(err as any).permanent = true
        throw err
      }

      // Transient errors — retry with backoff
      throw new Error(`Provider error: ${res.status}`)
    },
  }
}

import type { EmailProvider } from "@notifykitjs/core"

export function failoverEmailProvider(
  providers: EmailProvider[]
): EmailProvider {
  return {
    id: providers.map(p => p.id).join("+"),
    async send(input) {
      let lastError: Error | null = null

      for (const provider of providers) {
        try {
          return await provider.send(input)
        } catch (err) {
          lastError = err instanceof Error ? err : new Error(String(err))
          // If permanent error, don't try the next provider either
          if ((lastError as any).permanent) throw lastError
          // Otherwise, try the next provider
        }
      }

      // All providers failed with transient errors
      throw lastError!
    },
  }
}

import { resendProvider } from "@notifykitjs/resend"

const notify = createNotifyKit({
  // ...
  providers: {
    email: failoverEmailProvider([
      resendProvider({ apiKey: process.env.RESEND_API_KEY!, from: "app@example.com" }),
      postmarkProvider({ token: process.env.POSTMARK_TOKEN!, from: "app@example.com" }),
    ]),
  },
})

import { fakeEmailProvider } from "@notifykitjs/core"
import { resendProvider } from "@notifykitjs/resend"

export function emailProvider() {
  switch (process.env.NODE_ENV) {
    case "production":
      return resendProvider({
        apiKey: process.env.RESEND_API_KEY!,
        from: process.env.EMAIL_FROM!,
      })

    case "test":
      return fakeEmailProvider() // logs only, no network

    default: // development
      return process.env.RESEND_API_KEY
        ? resendProvider({ apiKey: process.env.RESEND_API_KEY, from: "dev@localhost" })
        : fakeEmailProvider()
  }
}

// lib/notifykit.ts
import { emailProvider } from "./providers"

export const notify = createNotifyKit({
  notifications: [...] as const,
  database: adapter(),
  providers: { email: emailProvider() },
})

createNotifyKit({
  // ...
  on: {
    "delivery.sent": ({ delivery }) => {
      metrics.inc("notifykit.delivery.sent", {
        provider: delivery.provider,
        channel: delivery.channel,
      })
      metrics.histogram("notifykit.delivery.latency_ms", delivery.latencyMs, {
        provider: delivery.provider,
      })
    },
    "delivery.failed": ({ delivery }) => {
      metrics.inc("notifykit.delivery.failed", {
        provider: delivery.provider,
        channel: delivery.channel,
        permanent: String(delivery.permanent),
      })
      // Alert if failure rate spikes
      if (delivery.attempts >= 3) {
        alerting.warn(`Provider ${delivery.provider} failing after ${delivery.attempts} attempts: ${delivery.error}`)
      }
    },
    "delivery.retrying": ({ delivery }) => {
      metrics.inc("notifykit.delivery.retry", {
        provider: delivery.provider,
        attempt: String(delivery.attempts),
      })
    },
  },
})