Newsletter

Cara kerja

Server situs Anda mengirim satu kolom, contact, ke ATLAS. Email mendapat email konfirmasi dan baru menjadi pelanggan setelah orangnya mengeklik tautan (double opt in). Nomor WhatsApp disimpan bersama persetujuannya dan belum dikirimi apa pun. Setiap email membawa tautan berhenti berlangganan sekali klik, dan berhenti berlaku saat itu juga.

Panggil endpoint dari server Anda dengan read token brand, jangan dari browser, dan kirim alamat serta user agent pengunjung di X-Atlas-Client-Ip dan X-Atlas-Client-User-Agent.

Persiapan

1. Simpan integrasi Turnstile (atau hCaptcha) dengan site key dan secret key.
2. Simpan pengaturan brand newsletter dengan minimal satu teks persetujuan: {"consent_texts": {"footer-2026-11": {"text": {"id": "...", "en": "..."}, "policy_url": "https://..."}}}. Kunci opsional: tags (kunci tag yang boleh dikirim situs), channels (email, whatsapp), confirmed_url dan unsubscribed_url (halaman https setelah konfirmasi dan berhenti berlangganan).
3. Nyalakan modul: PUT /v1/manage/modules/newsletter dengan {"enabled": true}. Tanpa captcha yang berfungsi jawabannya 422 captcha_not_ready beserta alasannya.

Ambil tantangan dan pengaturan captcha

Menjawab tantangan Shield (token, min_seconds, expires_in, pow) dan pengaturan widget captcha di captcha: provider, site_key, action (selalu newsletter_subscribe), mode, theme, size, appearance. Selesaikan proof of work (angka yang SHA-256 bersama salt sama dengan challenge) lalu tampilkan widget dengan site key dan action itu. Server situs juga bisa membaca data.newsletter.captcha dari GET /v1/public/shield saat mulai.

Berlangganan

{"contact": "0812 3456 7890", "locale": "id", "source": "footer",
 "tags": ["promo"], "consent_version": "footer-2026-11",
 "challenge": "<token>", "solution": 4711, "captcha_token": "<token turnstile>", "website": ""}

Setelah setiap jawaban, ambil tantangan baru dan reset widget captcha: keduanya hanya bisa dipakai sekali.

Tautan konfirmasi dan berhenti berlangganan

Email konfirmasi menautkan ke /v1/newsletter/confirm/{token} (berlaku 72 jam) dan setiap email membawa header List-Unsubscribe dan List-Unsubscribe-Post yang menunjuk ke /v1/newsletter/unsubscribe/{token}. Membuka tautan menampilkan halaman dengan satu tombol dan tidak mengubah apa pun; tombolnya (POST) yang mengonfirmasi atau menghentikan langganan. Aplikasi email memakai POST sekali klik langsung. Dengan Accept: application/json jawabannya {"data": {"status": "subscribed"}} atau {"data": {"status": "unsubscribed"}}; tautan yang tidak dikenal atau kedaluwarsa menjawab 404 link_expired.

Kelola pelanggan

Di bawah /v1/manage/newsletter: GET subscribers (filter status, source, channel, search alamat persis), GET subscribers/{id}, GET summary. Semua anggota bisa membacanya; editor melihat alamat tersamar, publisher dan admin melihat alamat lengkap. Admin bisa POST subscribers/{id}/suppress dan DELETE subscribers/{id} (hapus sekarang). Data yang berhenti berlangganan dihapus setelah 7 hari, pendaftaran yang tidak dikonfirmasi setelah 14 hari (nomor WhatsApp setelah 30 hari), dan hash alamat tetap di daftar blokir.