Anmeldungen aus deinem eigenen Newsletter-Formular an Kit senden

Sende dein eigenes Formular an Ikiform und richte einen Ikiform-Webhook auf ein Relay aus, das bis zu drei Aufrufe der Kit-v4-API macht: den Abonnenten anlegen, ihn einem Kit-Formular hinzufügen und taggen, wo er sich angemeldet hat. Lege ihn als inactive an und füge ihn einem Formular mit aktivierter Incentive-E-Mail hinzu, dann sollte Kit seine eigene Bestätigung senden; teste das einmal mit einer Adresse, die dir gehört, denn Kit dokumentiert es nur für seinen Bulk-Endpunkt. Das Relay hält den Kit-API-Key; deine Seite sieht ihn nie.

Was bei Kit anders ist

Kit teilt eine Anmeldung in separate Objekte auf. Ein Abonnent ist eine Person. Ein Formular ist, woher sie kam, und es trägt die Bestätigungs-E-Mail, die Kit auch Incentive-E-Mail nennt: seinen Double-Opt-in-Schritt. Ein Tag ist ein Label zum Segmentieren. Die v4-API hat für jedes einen Endpunkt, und sowohl der Formular- als auch der Tag-Endpunkt brauchen einen existierenden Abonnenten. Also wird eine Ikiform-Anmeldung zu einer kurzen Folge von Aufrufen, in dieser Reihenfolge:

Kit einrichten

1. Lege in Kit ein Formular für diese Anmeldungen an, etwa „Website signup“. Du bettest es nicht ein; es ist der Nachweis, woher Abonnenten kamen, und das Zuhause der Incentive-E-Mail.
2. Öffne die Einstellungen des Formulars und aktiviere die Incentive-E-Mail, wenn du Double Opt-in willst. Schreib die E-Mail und leg fest, wohin der Bestätigungslink führt.
3. Finde die numerische ID des Formulars, in der Kit-App oder mit dem Endpunkt der API, der Formulare auflistet. Lege pro Platzierung einen Tag an, wenn du welche willst, und notiere ihre IDs.
4. Erstelle in den Entwicklereinstellungen von Kit einen v4-API-Key und bewahre ihn für die Umgebung des Relays auf.

Das Relay

Ein Next.js Route Handler empfängt den Webhook, und ein kleines Modul spricht mit Kit. Dieselben zwei Dateien laufen auf jedem Node- oder Edge-Host, der dir eine öffentliche HTTPS-URL gibt.

const KIT = "https://api.kit.com/v4";

const TAGS: Record<string, number> = {
  footer: 1111111,
  post: 2222222,
};

function call(path: string, body: Record<string, unknown>) {
  return fetch(`${KIT}${path}`, {
    method: "POST",
    headers: {
      "X-Kit-Api-Key": process.env.KIT_API_KEY!,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(body),
  });
}

export async function addToKit(signup: { email: string; firstName?: string; source: string; referrer?: string }) {
  const created = await call("/subscribers", {
    email_address: signup.email,
    first_name: signup.firstName ?? null,
    state: "inactive",
  });
  if (!created.ok) return created;

  const joined = await call(`/forms/${process.env.KIT_FORM_ID}/subscribers`, {
    email_address: signup.email,
    referrer: signup.referrer ?? null,
  });
  if (!joined.ok) return joined;

  const tag = TAGS[signup.source];
  if (!tag) return joined;
  return call(`/tags/${tag}/subscribers`, { email_address: signup.email });
}

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { addToKit } from "@/lib/kit";

export async function POST(request: Request) {
  const payload = await request.text();
  let event;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  if (event.type !== "submission.created") return new Response(null, { status: 204 });

  const { email, first_name, consent, source } = event.data.fields;
  if (consent !== true || typeof email !== "string") return new Response("Skipped", { status: 200 });

  const answer = await addToKit({
    email,
    firstName: typeof first_name === "string" ? first_name : undefined,
    source: typeof source === "string" ? source : "unknown",
    referrer: typeof event.data.meta.referrer === "string" ? event.data.meta.referrer : undefined,
  });

  if (answer.status === 429) return new Response("Kit rate limit", { status: 503, headers: { "retry-after": "60" } });
  if (!answer.ok) return new Response(`Kit answered ${answer.status}: ${await answer.text()}`, { status: 502 });
  return new Response(null, { status: 204 });
}

IKIFORM_WEBHOOK_SECRET=whsec_...
KIT_API_KEY=your-v4-api-key
KIT_FORM_ID=1234567

• X-Kit-Api-Key ist der Weg, wie die v4-API von Kit einen persönlichen API-Key annimmt. OAuth ist für Apps, die andere Leute installieren; ein Relay für deine eigene Liste braucht es nicht.
• state: "inactive" zu senden, hält einen neuen Abonnenten unbestätigt, bis er klickt. Lässt du es weg, legt Kit ihn als active an, und der Status lässt sich später über denselben Endpunkt nicht ändern.
• Der Referrer der Seite geht als referrer des Formulars an Kit, sodass Kit zeigt, von welchem Artikel der Leser kam.
• Der Fehler-Body von Kit kommt in den 502, sodass das Zustellungsprotokoll in Ikiform Kits eigene Meldung zeigt.
• Ordne jedem source-Wert in TAGS eine Tag-ID zu. Eine source ohne Tag überspringt den dritten Aufruf.

Füge die URL der Route unter Webhooks im Ikiform-Dashboard hinzu, wähle das Newsletter-Formular und kopiere das whsec_-Secret in IKIFORM_WEBHOOK_SECRET. Jede Regel für die URL und jede Antwort steht in der Webhook-Doku.

Rate-Limits und Wiederholungen

Kit erlaubt 120 Requests pro rollierenden 60 Sekunden für einen API-Key. Jede Anmeldung kostet zwei oder drei, also passen etwa 40 bis 60 Anmeldungen pro Minute, bevor Kit mit 429 antwortet. Für ein Footer-Formular ist das reichlich, und knapp an dem Tag, an dem ein Beitrag viral geht.

Das Relay antwortet mit 503 und Retry-After, wenn Kit 429 sagt, und Ikiform wartet, bevor es erneut versucht. Eine Wiederholung führt die ganze Folge von vorn aus. Das ist sicher: Create gibt für einen existierenden Abonnenten 200 zurück, und jemanden hinzuzufügen, der schon im Formular ist, gibt 200 zurück. Laut Kits Doku zu Bulk-Formularen bekommen Leute, die schon in einem Formular sind, die Incentive-E-Mail nicht erneut; der Einzel-Endpunkt sagt dazu nichts, also teste eine Wiederholung mit einer Adresse, die dir gehört. Dein eigener Server zeigt, wie du jede webhook-id festhältst, wenn du bereits abgeschlossene Wiederholungen lieber überspringst.

Stolperfallen

• Benutzerdefinierte Felder müssen zuerst existieren. Fügst du dem Create-Aufruf fields hinzu, nutze den Key jedes Felds, etwa last_name, und lege das Feld in Kit an, bevor du es sendest.
• Aktive Abonnenten bleiben aktiv. Weil Create nie den Status eines bestehenden Abonnenten ändert, wird ein bestätigter Leser, der sich erneut anmeldet, nicht noch einmal um Bestätigung gebeten.
• Abgemeldete Leser. Ein Leser, der sich abgemeldet hat und erneut anmeldet, existiert schon, also gibt Create 200 zurück und ändert seinen Status nicht. Prüf in Kit, wie du mit ihnen umgehen willst.
• Ein Formular, viele Platzierungen. Nutze ein Kit-Formular für die Website und Tags für die Platzierungen. Mehrere Kit-Formulare bedeuten mehrere Incentive-E-Mails, die du synchron halten musst.
• Keine E-Mail von Ikiform. Ikiform schreibt der Person, die das Formular ausfüllt, keine E-Mail. Benachrichtigungs-E-Mails gehen nur an dich und dein Team, es gibt also keinen Autoresponder, keine Bestätigungs-E-Mail und kein Double Opt-in. Verschick diese aus deinem E-Mail-Tool, ausgelöst durch einen Webhook.

Prüfen, ob es funktioniert

1. Wähle Send test am Endpunkt in Ikiform. Die Zustellung zeigt 204, und in Kit ändert sich nichts.
2. Abonniere auf deiner Seite mit einer Adresse, die dir gehört. Die Zustellung zeigt 204.
3. In Kit erscheint der Abonnent unbestätigt in deinem Formular, mit dem Tag der Platzierung.
4. Die Incentive-E-Mail kommt an. Klick auf den Link, und der Abonnent wird bestätigt.
5. Abonniere erneut mit derselben Adresse. Die Zustellung zeigt 204, und es kommt keine zweite Incentive-E-Mail.
6. Setze kurz eine falsche KIT_FORM_ID. Die Zustellung zeigt 502 mit Kits 404-Meldung.

Fragen