# Kirim pendaftaran dari formulir newsletter Anda sendiri ke Kit

> Hubungkan formulir newsletter Anda sendiri ke Kit dengan relay yang membuat subscriber, menambahkannya ke formulir Kit untuk incentive email, dan memberi tag penempatannya.

Terbit 2026-10-25 · https://ikiform.com/id/guides/newsletter-signup/kit

Kirim formulir Anda sendiri ke Ikiform, dan arahkan webhook Ikiform ke relay yang melakukan hingga tiga panggilan API Kit v4: membuat subscriber, menambahkannya ke formulir Kit, dan memberi tag tempat mereka mendaftar. Buat mereka sebagai `inactive` dan tambahkan ke formulir yang incentive email-nya aktif, maka Kit seharusnya mengirim konfirmasinya sendiri, yang perlu Anda uji sekali dengan alamat milik Anda karena Kit hanya mendokumentasikannya untuk endpoint bulk. Relay memegang API key Kit; halaman Anda tidak pernah melihatnya.

## Apa yang berbeda dengan Kit

Kit memecah pendaftaran menjadi objek-objek terpisah. Subscriber adalah orang. Form adalah asal mereka, dan membawa email konfirmasi, yang juga disebut Kit sebagai incentive email: langkah double opt-in-nya. Tag adalah label untuk segmentasi. API v4 punya satu endpoint untuk masing-masing, dan endpoint form maupun tag butuh subscriber yang sudah ada lebih dulu. Jadi satu pendaftaran Ikiform menjadi rangkaian panggilan singkat, berurutan:

Diagram: Panggilan API Kit yang dilakukan relay untuk satu pendaftaran

1. Relay menerima webhook bertanda tangan dari Ikiform dan memverifikasinya.
2. Relay membuat subscriber di Kit sebagai inactive. Jika alamatnya sudah ada, Kit memperbarui nama depan dan membiarkan state-nya.
3. Relay menambahkan subscriber ke formulir Kit Anda. Jika incentive email formulir itu aktif, Kit mengirim konfirmasi.
4. Jika source pendaftaran punya tag, relay memberi tag pada subscriber. Langkah ini opsional.

Setiap panggilan bergantung pada panggilan sebelumnya, jadi relay berhenti di kegagalan pertama dan membiarkan Ikiform mencoba ulang.

| Panggilan | Jawaban Kit | Arti |
| --- | --- | --- |
| Create subscriber | `201` | Subscriber baru, dibuat dalam state yang Anda kirim |
| Create subscriber | `200` | Sudah ada. Nama depan diperbarui, state tidak berubah |
| Add to form | `201` atau `200` | Ditambahkan, atau sudah ada di formulir. Dokumentasi bulk form Kit menyatakan orang yang sudah ada di formulir tidak mendapat incentive email lagi |
| Panggilan apa pun | `401` | API key salah atau tidak ada |
| Add to form atau tag | `404` | ID formulir atau tag tidak ada di akun ini |
| Panggilan apa pun | `429` | Melewati rate limit API key |

## Siapkan Kit

1. Di Kit, buat formulir untuk pendaftaran ini, misalnya "Pendaftaran website". Anda tidak akan meng-embed-nya; formulir itu adalah catatan asal subscriber dan tempat incentive email berada.
2. Buka pengaturan formulir dan aktifkan incentive email jika Anda menginginkan double opt-in. Tulis email-nya dan atur ke mana tautan konfirmasi mengarah.
3. Temukan ID numerik formulir, di aplikasi Kit atau dengan endpoint list forms di API. Buat tag per penempatan jika Anda mau, dan catat ID-nya.
4. Buat API key v4 di pengaturan developer Kit dan simpan untuk environment relay.

> Dokumentasi API Kit menyatakan akses API bergantung pada paket akun yang memenuhi syarat, dan halaman harganya mencantumkan aplikasi dan integrasi mulai dari paket Creator. Pastikan paket Anda bisa membuat key v4 sebelum membangun di atasnya.

## Relay

Route handler Next.js menerima webhook dan modul kecil berkomunikasi dengan Kit. Dua file yang sama berjalan di host Node atau edge mana pun yang memberi Anda URL HTTPS publik.

`lib/kit.ts`:

```ts
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 });
}
```

`app/api/kit/route.ts`:

```ts
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 });
}
```

`.env.local`:

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

- `X-Kit-Api-Key` adalah cara API v4 Kit menerima API key pribadi. OAuth untuk aplikasi yang dipasang orang lain; relay untuk daftar Anda sendiri tidak membutuhkannya.
- Mengirim `state: "inactive"` adalah yang menjaga subscriber baru tetap belum terkonfirmasi sampai mereka mengklik. Hilangkan itu dan Kit membuat mereka sebagai `active`, dan state tidak bisa diubah nanti lewat endpoint yang sama.
- Referrer halaman dikirim ke Kit sebagai `referrer` formulir, jadi Kit menampilkan artikel asal pembaca.
- Body error dari Kit dimasukkan ke `502`, jadi log pengiriman di Ikiform menampilkan pesan Kit sendiri.
- Petakan setiap nilai `source` ke ID tag di `TAGS`. Source tanpa tag melewati panggilan ketiga.

Tambahkan URL route di **Webhooks** di dashboard Ikiform, pilih formulir newsletter, dan salin secret `whsec_` ke `IKIFORM_WEBHOOK_SECRET`. Setiap aturan untuk URL dan setiap jawaban ada di [dokumentasi webhook](https://ikiform.com/id/docs/webhooks.md).

## Rate limit dan percobaan ulang

Kit mengizinkan 120 request per 60 detik bergulir untuk satu API key. Setiap pendaftaran memakai dua atau tiga, jadi kira-kira 40 sampai 60 pendaftaran per menit muat sebelum Kit menjawab `429`. Itu lebih dari cukup untuk formulir footer, dan mepet di hari sebuah artikel viral.

Relay menjawab `503` dengan `Retry-After` saat Kit menyatakan `429`, dan Ikiform menunggu sebelum mencoba lagi. Percobaan ulang menjalankan seluruh rangkaian dari awal. Itu aman: create mengembalikan `200` untuk subscriber yang sudah ada, dan menambahkan orang yang sudah ada di formulir mengembalikan `200`. Dokumentasi bulk form Kit menyatakan orang yang sudah ada di formulir tidak mendapat incentive email lagi; endpoint tunggal tidak menyebutkannya, jadi uji percobaan ulang dengan alamat milik Anda. [Server Anda sendiri](https://ikiform.com/blog/form-submissions-to-your-own-server.md) menunjukkan cara mencatat setiap `webhook-id` jika Anda lebih suka melewati percobaan ulang yang sudah selesai.

## Hal yang sering menjebak

- **Custom field harus ada lebih dulu.** Jika Anda menambahkan `fields` ke panggilan create, gunakan key setiap field, seperti `last_name`, dan buat field itu di Kit sebelum Anda mengirimnya.
- **Subscriber aktif tetap aktif.** Karena create tidak pernah mengubah state subscriber yang sudah ada, pembaca terkonfirmasi yang mendaftar lagi tidak diminta mengonfirmasi lagi.
- **Pembaca yang sudah berhenti berlangganan.** Pembaca yang sudah unsubscribe lalu mendaftar lagi sudah ada, jadi create mengembalikan `200` dan tidak mengubah state-nya. Tentukan di Kit bagaimana Anda ingin menangani mereka.
- **Satu formulir, banyak penempatan.** Gunakan satu formulir Kit untuk website dan tag untuk penempatan. Beberapa formulir Kit berarti beberapa incentive email yang harus diselaraskan.
- **Tidak ada email dari Ikiform.** Ikiform tidak mengirim email ke orang yang mengisi formulir. Email notifikasi hanya dikirim ke Anda dan tim Anda, jadi tidak ada autoresponder, email konfirmasi, atau double opt-in. Kirim semua itu dari alat email Anda, dipicu oleh [webhook](https://ikiform.com/id/docs/webhooks.md).

## Pastikan berfungsi

1. Pilih **Send test** di endpoint di Ikiform. Pengiriman menampilkan `204`, dan tidak ada yang berubah di Kit.
2. Berlangganan di halaman Anda dengan alamat milik Anda. Pengiriman menampilkan `204`.
3. Di Kit, subscriber tampil di formulir Anda sebagai belum terkonfirmasi, dengan tag penempatannya.
4. Incentive email tiba. Klik tautannya dan subscriber menjadi terkonfirmasi.
5. Berlangganan lagi dengan alamat yang sama. Pengiriman menampilkan `204` dan tidak ada incentive email kedua.
6. Atur `KIT_FORM_ID` yang salah sejenak. Pengiriman menampilkan `502` dengan pesan `404` dari Kit.

## Pertanyaan

### Bisakah saya memakai formulir HTML sendiri dengan Kit alih-alih embed Kit?

Bisa. Kirim formulir Anda ke Ikiform dan biarkan relay menambahkan setiap pendaftaran lewat API v4 Kit: buat subscriber, tambahkan ke formulir Kit, dan opsional beri tag. Kit memperlakukan mereka sebagai berasal dari formulir itu.

### Apakah Kit akan mengirim email konfirmasi untuk pendaftaran dari formulir saya sendiri?

Seharusnya ya, jika relay membuat subscriber sebagai inactive dan menambahkannya ke formulir Kit yang incentive email-nya aktif. Dokumentasi bulk form Kit menyatakan menambahkan subscriber ke formulir double opt-in mengirim incentive email. Endpoint single-subscriber yang dipakai relay ini tidak menyebutkannya, jadi uji dengan alamat milik Anda.

### Apakah saya butuh alur OAuth Kit?

Tidak. OAuth untuk aplikasi yang dipasang pengguna Kit lain. Untuk daftar Anda sendiri, API key v4 di header X-Kit-Api-Key sudah cukup, dan key itu tetap di environment relay.

### Berapa banyak pendaftaran per menit yang bisa ditangani relay?

Kit mengizinkan 120 request per 60 detik bergulir per API key, dan setiap pendaftaran memakai dua atau tiga request, jadi sekitar 40 sampai 60 per menit. Lebih dari itu relay menjawab 503 dan Ikiform mencoba ulang nanti.

### Bisakah saya menghubungkan Kit tanpa kode?

Bisa. Arahkan webhook Ikiform ke Zapier atau Make dan gunakan action Kit mereka untuk menambahkan subscriber ke formulir. Periksa opsi action untuk tag dan formulirnya.

## Panduan lainnya

- [Formulir pendaftaran newsletter](https://ikiform.com/id/guides/newsletter-signup.md): Buat formulir pendaftaran newsletter dengan markup Anda sendiri, catat persetujuan, blokir pendaftaran bot, dan teruskan setiap subscriber ke Kit, MailerLite, beehiiv, atau alat apa pun.
- [Double opt-in](https://ikiform.com/id/guides/newsletter-signup/double-opt-in.md): Ikiform tidak mengirim email konfirmasi, jadi double opt-in berjalan di alat email Anda: relay menambahkan setiap pendaftaran sebagai belum terkonfirmasi dan alat itu mengirim tautannya.
- [MailerLite](https://ikiform.com/id/guides/newsletter-signup/mailerlite.md): Hubungkan formulir pendaftaran Anda sendiri ke MailerLite: relay menambahkan pembaca baru sebagai belum terkonfirmasi untuk double opt-in dan tidak pernah meminta subscriber mengonfirmasi dua kali.
- [beehiiv](https://ikiform.com/id/guides/newsletter-signup/beehiiv.md): Hubungkan formulir pendaftaran Anda sendiri ke beehiiv: relay membuat setiap subscription dengan double opt-in aktif, penempatan sebagai UTM source, dan halaman sebagai referrer.
- [Situs statis](https://ikiform.com/id/guides/newsletter-signup/static-site.md): Tambahkan formulir pendaftaran newsletter ke situs statis Hugo, Jekyll, Eleventy, atau Astro, jauhkan API key alat email dari halaman, dan lakukan konfirmasi di alat itu.
- [Formulir newsletter Next.js](https://ikiform.com/id/guides/newsletter-signup/nextjs.md): Formulir newsletter di footer Next.js: server action dengan pemeriksaan persetujuan dan Turnstile, mengirim ke Ikiform, plus route handler yang menambahkan pembaca ke Kit.