Buat dan Kelola API Key Anda

Published: 16 Juli 2026 · Last updated: 21 Juli 2026 · By Marcus Biel

Halaman API Key memberikan akses terautentikasi kepada sistem eksternal ke endpoint API Maildroppa yang didukung di akun Anda.

Anda dapat membuat satu API key, menyalin nilai rahasianya secara lengkap, meresetnya dengan aman melalui rotasi, atau menghapusnya saat tidak lagi diperlukan. API key akun yang sama dapat digunakan oleh integrasi sisi server dan pemicu permintaan API di Maildroppa Automations.

API key mewakili akun Maildroppa Anda. Perlakukan seperti kata sandi: siapa pun yang memperoleh key tersebut dapat memanggil endpoint API yang tersedia untuk key itu sampai Anda merotasi atau menghapusnya.

Untuk Apa API Key Digunakan

Gunakan API key ketika perangkat lunak di luar Maildroppa perlu berinteraksi dengan Maildroppa tanpa login pengguna interaktif.

Contoh umumnya meliputi:

• Menyinkronkan subscriber dengan CRM, toko, sistem keanggotaan, atau database internal.
• Membuat atau memperbarui subscriber dari aplikasi sisi server.
• Membaca atau mengelola tag, field, nilai field, dan segmen melalui endpoint yang didukung.
• Mengirim event khusus ke pemicu permintaan API dalam Automation.
• Mengirim Email Messages transaksional melalui API.
• Mengelola langganan webhook berbasis API.

API key ditujukan untuk komunikasi server-ke-server. API key tidak ditujukan untuk kode yang berjalan di browser pengunjung, situs web publik, aplikasi seluler, atau formulir pendaftaran tertanam.

Halaman ini saat ini ditandai “beta”. Gunakan dokumentasi OpenAPI tertaut sebagai sumber untuk endpoint, body permintaan, parameter, dan skema respons yang saat ini didukung API.

Membuka Halaman API Key

Buka “Settings”, perluas “Developers”, lalu pilih “API key”.

Anda juga dapat membuka halaman secara langsung di:

https://app.maildroppa.com/settings/developers/api-key

Halaman ini berisi:

• Panel API key dengan lencana beta.
• Tautan “View OpenAPI docs”.
• Status kosong dan tombol “Create API key” ketika belum ada key.
• Representasi tersamarkan dari key saat ini ketika key tersedia.
• Tombol “Copy” yang menyalin key secara lengkap.
• Tindakan “Rotate API key” dan “Delete API key” untuk mengganti atau menghapus key saat ini.

Maildroppa mengizinkan satu API key per akun. Halaman ini tidak membuat key terpisah untuk aplikasi, lingkungan, atau anggota tim tertentu.

Membuat API Key

Saat halaman menampilkan “No API key yet”, klik “Create API key”.

Maildroppa segera membuat key. Tidak ada dialog konfirmasi untuk pembuatan pertama ini. Saat permintaan sedang diproses, tombol berubah menjadi “Creating API key” dan halaman menonaktifkan sementara tindakan key lainnya.

Setelah key dibuat:

• Status kosong menghilang.
• Key tersamarkan muncul.
• Tindakan “Copy”, “Rotate API key”, dan “Delete API key” tersedia.
• Maildroppa menampilkan pesan sukses “API key updated”.

Jika akun sudah memiliki key lain, Maildroppa tidak membuat key kedua. Gunakan key yang ada atau rotasikan.

Memahami Key yang Tersamarkan

Halaman ini tidak menampilkan rahasia lengkap sebagai teks biasa. Halaman menampilkan lima karakter pertama diikuti lima tanda bintang, misalnya:

a1b2c*****

Ini hanya penyamaran visual. Tanda bintang tidak menunjukkan panjang key yang sebenarnya, dan nilai yang tersamarkan tidak dapat digunakan untuk permintaan API.

Klik “Copy” untuk menulis key lengkap saat ini ke clipboard. Setelah berhasil disalin, tombol berubah sebentar menjadi “Copied!”.

Key tetap tersamarkan saat Anda kembali ke halaman, tetapi “Copy” tetap menyalin nilai lengkap saat ini. Jadi, Anda tidak perlu merotasi key yang valid hanya karena tidak menyimpannya saat pembuatan.

Menyimpan Key dengan Aman

Pindahkan key yang telah disalin langsung ke penyimpanan rahasia yang digunakan integrasi.

Lokasi yang sesuai meliputi:

• Pengelola rahasia terkelola.
• Konfigurasi lingkungan server yang terlindungi.
• Rahasia deployment terenkripsi.
• Pengelola kata sandi yang digunakan untuk pemulihan operasional.

Jangan simpan key di:

• JavaScript sisi browser atau bundle frontend lain yang dapat diunduh.
• File kode sumber publik atau privat yang di-commit ke repositori.
• URL atau parameter kueri.
• Dokumentasi publik, tangkapan layar, pesan dukungan, atau pelacak masalah.
• Log aplikasi bersama, event analitik, atau laporan error.
• Spreadsheet tidak terenkripsi atau chat tim biasa.

Jangan tambahkan key ke contoh curl yang akan disalin ke dokumentasi atau riwayat shell yang dibagikan kepada orang lain. Pilih variabel lingkungan seperti MAILDROPPA_API_KEY.

Menggunakan API Key

Kirim key lengkap dalam header permintaan HTTP X-API-Key:

X-API-Key: your-complete-api-key

Jangan mengirimkannya sebagai token Bearer. Maildroppa mengharapkan X-API-Key, bukan Authorization: Bearer ....

API produksi dan dokumentasi OpenAPI interaktifnya tersedia di:

https://api.maildroppa.com

Klik “View OpenAPI docs” di halaman API Key untuk membuka dokumentasi di tab browser baru. Pilih endpoint di sana untuk meninjau metode, path, parameter, body permintaan, tipe respons, dan kemungkinan kode statusnya.

Contoh Permintaan

Contoh berikut mengambil halaman pertama subscriber. Contoh ini membaca key dari variabel lingkungan, bukan menempatkan rahasia langsung di dalam perintah:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Atur variabel tersebut di lingkungan aman tempat integrasi berjalan. Metode, path, parameter kueri, dan body yang tepat bergantung pada endpoint. Salin detail tersebut dari dokumentasi OpenAPI, bukan dengan menebaknya dari tindakan yang tersedia di aplikasi Maildroppa.

Permintaan dengan Body JSON

Untuk permintaan yang mengirim JSON, sertakan juga:

Content-Type: application/json

Contoh struktur dasarnya:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint dan body-nya adalah placeholder. Ganti dengan endpoint yang terdokumentasi dan skema permintaannya yang terdokumentasi.

Apa yang Dapat Diakses oleh Key

Key hanya berfungsi dengan endpoint yang mendukung autentikasi API key. Halaman atau permintaan yang digunakan secara internal oleh aplikasi Maildroppa tidak otomatis menjadi bagian dari API pelanggan publik.

Dokumentasi OpenAPI menampilkan API pelanggan yang didukung. Jika suatu path tidak didokumentasikan untuk penggunaan API key, jangan berasumsi bahwa key dapat mengaksesnya.

Halaman API Key tidak menyediakan scope atau kotak centang izin per endpoint. Oleh karena itu, key akun saat ini harus diperlakukan sebagai kredensial bernilai tinggi meskipun satu integrasi hanya menggunakan satu endpoint.

Batas Laju

Kontrak OpenAPI saat ini mendokumentasikan batas API key berikut:

• API pelanggan default: 300 permintaan per menit dan 2.000 permintaan per jam.
• Events API di /events: 100 permintaan per detik dengan kapasitas burst 500 permintaan.

Batas ini diterapkan pada akun Maildroppa, bukan secara terpisah pada setiap skrip yang berbagi key. Oleh karena itu, beberapa integrasi dapat menggunakan jatah yang sama.

Saat Maildroppa mengembalikan 429 Too Many Requests, hentikan pengiriman permintaan baru dan patuhi header respons Retry-After jika tersedia. Gunakan antrean dan backoff terkontrol, bukan memulai banyak percobaan ulang secara paralel.

Kebijakan batas laju dapat berubah selama API masih dalam beta. Periksa informasi di bagian atas dokumentasi OpenAPI sebelum merancang integrasi bervolume tinggi.

Menggunakan Key untuk Permintaan API Automation

Automation dapat dimulai saat sistem Anda mengirim event khusus ke Events API Maildroppa.

Saat Anda mengonfigurasi pemicu “API request”, Maildroppa menggunakan API key akun yang sama yang dikelola di halaman ini. Penyiapan pemicu dapat membuat key jika belum ada dan dapat menyalin permintaan curl yang telah disiapkan dan berisi key lengkap.

Hal ini memiliki dua konsekuensi penting:

• Merotasi atau menghapus key akun juga memengaruhi sistem yang mengirim event khusus ke Automations.
• Contoh permintaan Automation yang disalin berisi rahasia di clipboard meskipun key tersamarkan di layar.

Sebelum merotasi atau menghapus key, masukkan setiap pemicu permintaan API dan setiap pengirim event eksternal ke inventaris integrasi Anda.

Mereset atau Mengganti API Key

Gunakan “Rotate API key” saat perlu mereset atau mengganti kredensial saat ini. Maildroppa membuat key baru dan membatalkan key sebelumnya sebagai bagian dari tindakan yang sama.

Gunakan rotasi ketika:

• Key mungkin telah terekspos.
• Seseorang atau penyedia yang mengetahui key tersebut tidak lagi memerlukan akses.
• Kebijakan keamanan Anda mewajibkan penggantian kredensial secara berkala.
• Anda ingin mengganti key yang disimpan di lokasi lama atau tidak aman.

Klik “Rotate API key” di bawah key yang tersamarkan. Maildroppa membuka dialog peringatan yang menjelaskan bahwa key yang ada tidak akan dapat digunakan lagi.

Klik “Rotate API key” di dialog untuk melanjutkan, atau klik “Cancel” untuk mempertahankan key saat ini.

Rotasi Tidak Memiliki Masa Tenggang

Setelah Anda mengonfirmasi rotasi, key lama langsung berhenti berfungsi. Maildroppa tidak mempertahankan key lama dan baru agar tetap valid secara bersamaan.

Karena akun hanya memiliki satu key, rotasi memengaruhi setiap server, tugas terjadwal, integrasi, skrip, dan pengirim event Automation yang menggunakannya.

Gunakan urutan berikut untuk rotasi terencana:

1. Daftarkan setiap integrasi yang menggunakan key saat ini.
2. Siapkan akses ke konfigurasi rahasia dan proses deployment setiap integrasi.
3. Pilih jendela pemeliharaan singkat jika akses API tanpa gangguan penting.
4. Klik “Rotate API key”, lalu konfirmasikan peringatan dengan “Rotate API key” di dialog.
5. Klik “Copy” untuk menyalin key baru secara lengkap.
6. Segera ganti rahasia di setiap integrasi.
7. Mulai ulang atau deploy ulang layanan yang hanya memuat rahasia saat startup.
8. Kirim permintaan terdokumentasi yang tidak berbahaya untuk memverifikasi setiap integrasi.
9. Periksa respons 401 Unauthorized dari layanan yang terlupakan dan masih menggunakan key lama.

Jika key saat ini diyakini telah disusupi, segera rotasikan dan terima gangguan singkat yang diperlukan untuk memperbarui sistem yang sah.

Menghapus API Key

Hapus key ketika akun tidak lagi boleh menerima permintaan yang diautentikasi dengan API key.

Klik “Delete API key” di bawah key yang tersamarkan. Maildroppa membuka dialog peringatan yang menjelaskan bahwa key akan dihapus secara permanen dari akun.

Klik “Delete API key” di dialog untuk menghapusnya, atau klik “Cancel” untuk mempertahankannya.

Setelah penghapusan:

• Key saat ini langsung berhenti berfungsi.
• Halaman kembali ke status “No API key yet”.
• Integrasi server yang menggunakan key yang dihapus tidak lagi dapat melakukan autentikasi.
• Pengirim permintaan API Automation yang menggunakan key tersebut tidak lagi dapat mengirimkan event.

Menghapus key tidak menghapus subscriber, campaign, tag, field, segmen, Automation, atau data akun lainnya. Penghapusan hanya menghapus kredensial yang digunakan untuk mengakses endpoint API yang didukung.

Anda dapat mengeklik “Create API key” nanti untuk membuat kredensial baru. Nilai yang dihapus tidak dipulihkan. Setiap integrasi harus diperbarui sebelum dapat menggunakan key baru.

Mereset atau Menghapus: Mana yang Harus Dipilih?

Pilih “Rotate API key” ketika akses API harus tetap berjalan dengan kredensial baru.

Pilih penghapusan ketika akses API harus dihentikan sepenuhnya, setidaknya untuk sementara.

Kedua tindakan langsung membatalkan key saat ini. Rotasi membuat pengganti sebagai bagian dari tindakan yang sama; penghapusan membuat akun tidak memiliki key.

Rekomendasi Keamanan

Simpan Panggilan API di Server Anda

Browser atau aplikasi seluler tidak dapat menjaga rahasia yang disematkan secara andal. Pengguna dapat memeriksa aplikasi, header permintaan, source map, atau lalu lintas jaringan dan mengambil key tersebut.

Jika situs web atau aplikasi perlu memicu suatu tindakan, kirim permintaan terlebih dahulu ke backend terautentikasi milik Anda. Biarkan backend tersebut memvalidasi pengguna dan memanggil Maildroppa dengan key yang disimpan di server.

Minimalkan Paparan

Berikan key hanya kepada sistem yang membutuhkannya. Jangan mendistribusikannya kepada setiap developer atau menempelkannya ke banyak file konfigurasi lokal.

Karena halaman ini saat ini mengelola satu key untuk seluruh akun, bukan beberapa key bernama atau berscope, gunakan layanan integrasi internal atau proxy jika beberapa aplikasi memerlukan isolasi yang lebih kuat satu sama lain.

Samarkan Header Permintaan

Konfigurasikan klien HTTP, reverse proxy, alat observabilitas, dan pelapor error untuk menyamarkan X-API-Key. Permintaan dapat berjalan dengan benar sekaligus tetap membocorkan kredensial melalui log debug.

Pisahkan Lingkungan

Jangan gunakan kembali key produksi untuk pengembangan lokal, kode contoh, tangkapan layar, atau fixture pengujian. Simpan rahasia khusus lingkungan di penyimpanan rahasia khusus lingkungan tersebut.

Tautan “View OpenAPI docs” secara otomatis mengarahkan pengguna produksi ke dokumentasi API produksi. Selalu verifikasi hostname sebelum mengirim key asli.

Rotasikan Setelah Paparan yang Dicurigai

Menghapus pesan, commit repositori, baris log, atau tangkapan layar tidak membuktikan bahwa tidak ada orang yang menyalin key. Jika nilai lengkap telah terekspos, rotasikan key tersebut.

Menangani Error API

Gunakan status HTTP dan body respons yang terdokumentasi untuk menentukan tindakan integrasi.

Kasus umum meliputi:

• 400 Bad Request — Path, parameter, atau body JSON tidak memenuhi kontrak endpoint. Bandingkan permintaan dengan skema OpenAPI.
• 401 Unauthorized — Header X-API-Key tidak ada, kosong, tidak valid, dihapus, atau berisi nilai lama setelah rotasi.
• 403 Forbidden — Key yang telah diautentikasi tidak diizinkan menggunakan operasi tersebut.
• 404 Not Found — Path atau resource yang dirujuk tidak ada di akun ini.
• 429 Too Many Requests — Integrasi telah mencapai batas laju API. Jeda permintaan dan patuhi header Retry-After jika tersedia.
• 5xx — Maildroppa tidak dapat menyelesaikan permintaan. Ulangi operasi yang aman dengan exponential backoff terbatas dan logging yang tidak menyertakan API key.

Jangan mengulangi setiap kegagalan secara membabi buta. Perbaiki respons 400, 401, 403, dan sebagian besar respons 404 sebelum mengirim permintaan yang sama lagi.

Untuk permintaan yang mengubah data, konfirmasikan perilaku percobaan ulang dan idempotensinya sebelum mengulangi permintaan secara otomatis. Kegagalan koneksi tidak selalu membuktikan bahwa Maildroppa tidak melakukan perubahan.

Pemecahan Masalah

“Create API key” Masih Terlihat

Saat ini tidak ada key di akun. Klik tombol sekali dan tunggu hingga permintaan selesai.

Jika pembuatan gagal, muat ulang halaman sebelum mencoba lagi. Halaman lain atau penyiapan Automation mungkin telah membuat key akun tersebut.

Key di Halaman Terlihat Terlalu Pendek

Halaman memang hanya menampilkan lima karakter pertama dan *****. Klik “Copy” untuk menyalin nilai lengkap. Jangan mengirim teks tersamarkan dalam permintaan.

“Copy” Tidak Berubah Menjadi “Copied!”

Browser mungkin memblokir akses clipboard. Pertahankan halaman di tab aktif, izinkan akses clipboard jika diminta, lalu klik “Copy” lagi.

Jangan mencoba merekonstruksi key dari teks yang tersamarkan.

Permintaan Mengembalikan 401 Unauthorized

Periksa bahwa:

• Nama header tepat X-API-Key.
• Header berisi nilai lengkap, tanpa tanda bintang yang terlihat.
• Integrasi tidak mengirim Authorization: Bearer sebagai gantinya.
• Spasi kosong, tanda kutip, atau baris baru tidak ditambahkan ke rahasia.
• Tidak ada yang merotasi atau menghapus key akun.
• Layanan dimulai ulang jika hanya membaca variabel lingkungan saat startup.
• Permintaan dikirim ke lingkungan API Maildroppa yang benar.

Satu Integrasi Berfungsi, tetapi Integrasi Lain Berhenti Setelah Rotasi

Integrasi kedua mungkin masih menggunakan key lama. Tidak ada periode tumpang tindih. Perbarui rahasianya dan mulai ulang proses yang menyimpan konfigurasi dalam cache.

Halaman OpenAPI Berfungsi, tetapi Endpoint Mengembalikan 403

Tidak setiap endpoint aplikasi mendukung autentikasi API key. Gunakan operasi yang didokumentasikan untuk API pelanggan dan konfirmasikan persyaratan autentikasinya di halaman OpenAPI.

Permintaan Mengembalikan 429 Too Many Requests

Kurangi lonjakan permintaan, antrekan pekerjaan, dan ulangi setelah jeda yang dikembalikan API. Hindari lonjakan percobaan ulang paralel. Jika beberapa aplikasi berbagi satu key akun, koordinasikan volume permintaan karena semuanya berbagi batas API akun.

Daftar Periksa Penyiapan yang Disarankan

Sebelum menggunakan integrasi secara rutin, pastikan bahwa:

• Key hanya disimpan dalam konfigurasi rahasia sisi server.
• Permintaan menggunakan header X-API-Key.
• Integrasi menggunakan https://api.maildroppa.com di produksi.
• Setiap metode, path, parameter, dan body JSON mengikuti dokumentasi OpenAPI.
• Log dan laporan error menyamarkan key.
• Timeout dan percobaan ulang terbatas telah dikonfigurasi.
• Error 401, 403, 429, dan error server dipantau.
• Pemilik integrasi dicatat.
• Setiap sistem yang berbagi key akun disertakan dalam rencana rotasi.
• Key yang disusupi dapat segera dirotasi.

Halaman API Key sengaja dibuat sederhana, tetapi tindakannya memengaruhi setiap integrasi API yang terhubung ke akun. Buat key hanya saat diperlukan, simpan di server tepercaya, dan rencanakan rotasi sebagai perubahan kredensial seluruh akun.