# Kirim pendaftaran dari formulir newsletter Anda sendiri ke beehiiv

> Hubungkan formulir pendaftaran Anda sendiri ke beehiiv: relay membuat setiap subscription dengan double opt-in aktif, penempatan sebagai UTM source, dan halaman sebagai referrer.

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

Kirim formulir Anda sendiri ke Ikiform dan arahkan webhook ke relay yang memanggil endpoint create subscription beehiiv. Kirim `double_opt_override: "on"` agar beehiiv mengirim email konfirmasi, teruskan penempatan formulir sebagai `utm_source` dan halaman sebagai `referring_site`, dan biarkan `reactivate_existing` bernilai false agar pendaftaran tidak pernah diam-diam membatalkan unsubscribe. Satu panggilan API per pendaftaran, dengan key disimpan di relay.

## Apa yang berbeda dengan beehiiv

API beehiiv disusun di sekitar publikasi. Subscription adalah alamat email yang berlangganan ke satu publikasi, dan Anda membuatnya dengan satu `POST` ke `/v2/publications/{publicationId}/subscriptions`. Semua hal tentang pendaftaran dibawa dalam satu request itu: apakah perlu konfirmasi, apakah mengirim email sambutan, dari mana pembaca berasal, dan custom field. Tidak ada langkah tag atau formulir terpisah seperti di [Kit](https://ikiform.com/id/guides/newsletter-signup/kit.md).

beehiiv juga melaporkan akuisisi dalam istilah UTM. Record subscription-nya membawa `utm_source`, `utm_medium`, `utm_campaign`, dan `referring_site`. Petakan field formulir Anda ke sana, dan setiap subscriber di beehiiv menampilkan penempatan dan artikel mana yang membawanya:

Diagram: Bagaimana relay memetakan kiriman Ikiform ke subscription beehiiv

1. fields.email menjadi email.
2. fields.source menjadi utm_source.
3. meta.referrer menjadi referring_site.
4. fields.first_name menjadi custom_fields: First Name.
5. double_opt_override: "on" ditambahkan oleh relay.
6. reactivate_existing: false ditambahkan oleh relay.

Empat yang pertama berasal dari event Ikiform. Dua yang terakhir adalah pilihan tetap yang dibuat relay untuk setiap pendaftaran.

## Siapkan beehiiv

1. Di beehiiv, buka **Settings**, lalu **API** di bawah **Workspace Settings**, dan pilih **Create New API Key**. Salin segera; beehiiv tidak akan menampilkannya lagi.
2. Di paket berbayar, batasi key ke satu publikasi yang diisi formulir. Key yang dibatasi ke publikasi mendapat `404` untuk publikasi lain, yang membatasi kerusakan jika bocor.
3. Temukan ID publikasi, ID berawalan yang dipakai API beehiiv di path. Endpoint list publications di API mengembalikannya.
4. Buat custom field bernama `First Name` jika Anda ingin menyimpan nama depan. beehiiv membuang custom field yang belum ada.
5. Siapkan email double opt-in dan email sambutan di pengaturan publikasi. Relay mengaktifkannya per request; isinya ada di beehiiv.

> Halaman harga beehiiv mencantumkan akses API di setiap paket, dengan rate limit API lebih rendah di paket yang lebih murah. Send API-nya, untuk mengirim email lewat API, terbatas di paket yang lebih tinggi, tetapi relay ini hanya membuat subscription dan tidak membutuhkannya.

## Relay

Ini adalah Netlify Function, yang cocok untuk situs yang sudah di Netlify: berjalan di domain Anda sendiri, di samping situs statis, tanpa layanan terpisah. Instal `@netlify/functions` untuk tipenya, dan atur ketiga variabel di pengaturan environment situs.

`netlify/functions/beehiiv.mts`:

```ts
import type { Config } from "@netlify/functions";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export default async (request: Request) => {
  const payload = await request.text();
  let event;
  try {
    event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: Netlify.env.get("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 publication = Netlify.env.get("BEEHIIV_PUBLICATION_ID");
  const answer = await fetch(`https://api.beehiiv.com/v2/publications/${publication}/subscriptions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Netlify.env.get("BEEHIIV_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email,
      double_opt_override: "on",
      send_welcome_email: true,
      reactivate_existing: false,
      utm_source: typeof source === "string" ? source : "website",
      utm_medium: "signup_form",
      referring_site: event.data.meta.referrer ?? undefined,
      custom_fields: typeof first_name === "string" && first_name ? [{ name: "First Name", value: first_name }] : [],
    }),
  });

  if (answer.status === 429) {
    const reset = Number(answer.headers.get("ratelimit-reset"));
    const wait = reset ? Math.max(1, reset - Math.floor(Date.now() / 1000)) : 60;
    return new Response("beehiiv rate limit", { status: 503, headers: { "retry-after": String(wait) } });
  }
  if (!answer.ok) return new Response(`beehiiv answered ${answer.status}: ${await answer.text()}`, { status: 502 });
  return new Response(null, { status: 204 });
};

export const config: Config = {
  path: "/hooks/beehiiv",
};
```

- `double_opt_override: "on"` mengirim email konfirmasi apa pun default publikasinya. Gunakan `"not_set"` untuk mengikuti pengaturan publikasi, dan jangan pernah `"off"` untuk formulir publik.
- `send_welcome_email` default-nya `false` di API. Atur ke `true` jika Anda ingin pendaftaran API mendapat email sambutan yang didapat pendaftaran dari embed.
- `reactivate_existing: false` juga merupakan default. Tuliskan secara eksplisit agar tidak ada yang mengubahnya nanti tanpa berpikir; nilai itu mengaktifkan kembali orang yang sudah unsubscribe.
- beehiiv menjawab `200` dengan subscription-nya, dan `status`-nya dimulai sebagai `validating` selama beehiiv memeriksa alamat, lalu `pending` sampai pembaca mengonfirmasi.
- Pada `429`, relay membaca `RateLimit-Reset` dari beehiiv, berupa waktu Unix, dan mengubahnya menjadi jeda `Retry-After` untuk Ikiform.

URL function-nya adalah `https://your-site.com/hooks/beehiiv`. Tambahkan di **Webhooks** di Ikiform dan salin secret `whsec_` ke `IKIFORM_WEBHOOK_SECRET`. [Dokumentasi webhook](https://ikiform.com/id/docs/webhooks.md) mendaftar aturan URL, dan [server Anda sendiri](https://ikiform.com/blog/form-submissions-to-your-own-server.md) menunjukkan cara melewati pengiriman yang sudah Anda tangani.

## Memilih nilai UTM

Field UTM beehiiv berupa teks bebas, jadi tentukan nilainya sekali dan jaga konsistensinya, atau record terpecah menjadi hampir-duplikat seperti `footer` dan `Footer`. Input tersembunyi `source` milik formulir adalah `utm_source` yang alami. Jaga `utm_medium` tetap, agar setiap pendaftaran dari formulir Anda sendiri bisa dibedakan dari halaman hosted beehiiv dan dari impor:

| Penempatan | Input `source` | `utm_source` | `utm_medium` |
| --- | --- | --- | --- |
| Footer situs | `footer` | `footer` | `signup_form` |
| Akhir artikel | `post` | `post` | `signup_form` |
| Halaman newsletter | `newsletter-page` | `newsletter-page` | `signup_form` |

Jika Anda menjalankan kampanye yang menautkan ke halaman berisi formulir, baca kampanye dari URL halaman di relay. `meta.referrer` berisi URL lengkap halaman, termasuk query string jika browser mengirimnya, jadi relay bisa menyalin parameter `utm_campaign` dari sana ke request.

## Rate limit per paket

beehiiv mengukur batasnya per API key dalam jendela tetap 60 detik, dan batasnya bergantung pada paket. Setiap pendaftaran adalah satu request:

| Paket beehiiv | Request per menit |
| --- | --- |
| Free | 30 |
| Lite | 180 |
| Pro | 500 |
| Enterprise | 800, lebih tinggi atas permintaan |

Tiga puluh per menit cukup untuk sebagian besar formulir footer, tetapi artikel peluncuran di publikasi gratis bisa melewatinya. `503` dari relay membuat Ikiform menunggu dan mencoba ulang alih-alih membuang pendaftaran. Nama paket dan batasnya bisa berubah, jadi periksa halaman rate limiting beehiiv jika paket Anda tidak tercantum.

## Hal yang sering menjebak

- **Nama custom field harus persis.** beehiiv mencocokkan custom field berdasarkan nama dan membuang yang tidak dikenal dengan peringatan di respons, bukan error. Salah ketik berarti nama depan hilang tanpa suara.
- **`referring_site` bisa kosong.** `meta.referrer` bernilai `null` saat browser tidak mengirim referrer, dan relay tidak menyertakan field itu.
- **Subscriber yang sudah ada.** Dokumentasi beehiiv menyatakan panggilan ini membuat atau memperbarui subscription, tetapi tidak menyebutkan apa yang berubah untuk subscriber aktif. Uji dengan alamat terkonfirmasi milik Anda sebelum memasang formulir di setiap halaman.
- **Key berlaku untuk seluruh workspace secara default.** Key tanpa pembatasan publikasi bisa menjangkau setiap publikasi di workspace. Batasi cakupannya.
- **Tier berbayar tetap di beehiiv.** Jangan sertakan `tier` agar pendaftaran bergabung tanpa langganan berbayar. Upgrade terjadi di checkout beehiiv sendiri.

## Pastikan berfungsi

1. Pilih **Send test** di endpoint di Ikiform. Pengiriman menampilkan `204` dan beehiiv tidak menerima request.
2. Berlangganan dari halaman Anda dengan alamat milik Anda. Pengiriman menampilkan `204`.
3. Di beehiiv, subscriber muncul sebagai pending, dengan penempatan Anda sebagai UTM source dan artikelnya sebagai referring site.
4. Email double opt-in tiba. Konfirmasi, lalu email sambutan menyusul.
5. Unsubscribe alamat itu di beehiiv lalu daftar lagi. Subscriber tetap inactive, karena `reactivate_existing` bernilai false.

## Pertanyaan

### Bisakah saya memakai formulir sendiri dengan beehiiv alih-alih embed-nya?

Bisa. Kirim formulir Anda ke Ikiform dan biarkan relay memanggil endpoint create subscription beehiiv untuk setiap pendaftaran. Formulir Anda tetap dengan desain Anda, dan beehiiv tetap mengonfirmasi, menyambut, dan mengirim email ke pembaca.

### Apakah API beehiiv tersedia di setiap paket beehiiv?

Halaman harga beehiiv mencantumkan akses API di setiap paket, dan halaman rate limiting-nya memberi paket terendah 30 request per menit. Send API terbatas di paket yang lebih tinggi, tetapi membuat subscription tidak memakainya.

### Bagaimana cara membuat beehiiv mengirim email double opt-in untuk pendaftaran API?

Kirim double_opt_override bernilai "on" di request create subscription, atau "not_set" untuk memakai pengaturan publikasi sendiri. "off" langsung membuat subscriber aktif tanpa email.

### Bisakah saya menghubungkan beehiiv tanpa kode?

Bisa. beehiiv bekerja dengan Zapier dan Make, yang mematuhi rate limit-nya untuk Anda. Arahkan webhook Ikiform ke otomasi dan gunakan action beehiiv-nya untuk menambahkan subscriber.

## 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.
- [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.
- [Kit (ConvertKit)](https://ikiform.com/id/guides/newsletter-signup/kit.md): Hubungkan formulir newsletter Anda sendiri ke Kit dengan relay yang membuat subscriber, menambahkannya ke formulir Kit untuk incentive email, dan memberi tag penempatannya.
- [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.
- [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.