Cipta dan urus kunci API anda

Diterbitkan: 16 Julai 2026 · Kemas kini terakhir: 12 September 2026 · Oleh Marcus Biel

Halaman kunci API membolehkan sistem luaran mengakses titik akhir API Maildroppa yang disokong dalam akaun anda melalui pengesahan.

Anda boleh mencipta satu kunci API, menyalin nilai rahsia penuhnya, menetapkannya semula dengan selamat melalui penggantian kunci (rotasi), atau memadamkannya apabila tidak lagi diperlukan. Kunci akaun yang sama boleh digunakan oleh integrasi pada pelayan dan pencetus permintaan API dalam automasi Maildroppa.

Kunci API mewakili akaun Maildroppa anda. Lindunginya seperti kata laluan: sesiapa yang memperoleh kunci itu boleh membuat panggilan ke titik akhir API yang tersedia untuknya sehingga anda menggantikan atau memadamkan kunci tersebut.

Kegunaan kunci API

Gunakan kunci API apabila perisian di luar Maildroppa perlu berinteraksi dengan Maildroppa tanpa memerlukan pengguna log masuk secara interaktif.

Contoh penggunaan lazim termasuk:

• Menyegerakkan pelanggan e-mel dengan CRM, kedai, sistem keahlian atau pangkalan data dalaman.
• Mencipta atau mengemas kini pelanggan e-mel daripada aplikasi pada pelayan.
• Membaca atau mengurus teg, medan, nilai medan dan segmen melalui titik akhir yang disokong.
• Menghantar peristiwa tersuai kepada pencetus permintaan API dalam automasi.
• Menghantar mesej e-mel transaksi melalui API.
• Mengurus langganan webhook berasaskan API.

Kunci API direka untuk komunikasi antara pelayan. Ia bukan untuk kod yang berjalan dalam pelayar pelawat, laman web awam, aplikasi mudah alih atau borang pendaftaran terbenam.

Halaman ini kini ditandakan sebagai “beta”. Rujuk dokumentasi OpenAPI yang dipautkan untuk mengetahui titik akhir, badan permintaan, parameter dan skema respons yang disokong oleh API pada masa ini.

Buka halaman kunci API

Buka “Settings”, kembangkan “Developers” dan pilih “API key”.

Anda juga boleh membuka halaman tersebut terus di:

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

Halaman ini mengandungi:

• Panel kunci API dengan lencana beta.
• Pautan “View OpenAPI docs”.
• Paparan kosong dan butang “Create API key” apabila belum ada kunci.
• Paparan kunci semasa yang disamarkan apabila kunci sudah wujud.
• Butang “Copy” untuk menyalin kunci penuh.
• Tindakan “Rotate API key” dan “Delete API key” untuk menggantikan atau mengalih keluar kunci semasa.

Maildroppa membenarkan satu kunci API bagi setiap akaun. Halaman ini tidak mencipta kunci berasingan untuk setiap aplikasi, persekitaran atau ahli pasukan.

Cipta kunci API

Apabila halaman memaparkan “No API key yet”, klik “Create API key”.

Maildroppa mencipta kunci serta-merta. Tiada dialog pengesahan untuk penciptaan kali pertama ini. Semasa permintaan diproses, teks butang bertukar kepada “Creating API key” dan tindakan lain berkaitan kunci dinyahdayakan buat sementara waktu.

Selepas kunci dicipta:

• Paparan kosong hilang.
• Kunci yang disamarkan dipaparkan.
• Tindakan “Copy”, “Rotate API key” dan “Delete API key” tersedia.
• Maildroppa memaparkan mesej kejayaan “API key updated”.

Jika akaun sudah mempunyai kunci, Maildroppa tidak akan mencipta kunci kedua. Gunakan kunci sedia ada atau gantikannya melalui rotasi.

Fahami paparan kunci yang disamarkan

Halaman ini tidak memaparkan nilai rahsia penuh sebagai teks biasa. Hanya lima aksara pertama diikuti lima tanda bintang dipaparkan, contohnya:

a1b2c*****

Penyamaran ini hanya melibatkan paparan. Tanda bintang tidak mewakili panjang sebenar kunci, dan nilai yang disamarkan tidak boleh digunakan dalam permintaan API.

Klik “Copy” untuk menyalin kunci semasa yang penuh ke papan keratan. Selepas berjaya disalin, teks butang bertukar seketika kepada “Copied!”.

Kunci kekal disamarkan apabila anda kembali ke halaman ini, tetapi “Copy” masih menyalin nilai semasa yang penuh. Jadi, anda tidak perlu menggantikan kunci yang sah hanya kerana tidak menyimpannya semasa kunci itu dicipta.

Simpan kunci dengan selamat

Pindahkan kunci yang disalin terus ke storan rahsia yang digunakan oleh integrasi.

Lokasi yang sesuai termasuk:

• Perkhidmatan pengurusan rahsia terurus.
• Konfigurasi persekitaran pelayan yang dilindungi.
• Rahsia pelaksanaan (deployment) yang disulitkan.
• Pengurus kata laluan yang digunakan untuk pemulihan operasi.

Jangan simpan kunci dalam:

• JavaScript yang berjalan dalam pelayar atau pakej kod bahagian hadapan lain yang boleh dimuat turun.
• Fail kod sumber awam atau peribadi yang dikomit ke repositori.
• URL atau parameter pertanyaan.
• Dokumentasi awam, tangkapan skrin, mesej sokongan atau penjejak isu.
• Log aplikasi yang dikongsi, peristiwa analitik atau laporan ralat.
• Hamparan yang tidak disulitkan atau sembang pasukan biasa.

Jangan masukkan kunci dalam contoh curl yang akan disalin ke dokumentasi atau sejarah shell yang dikongsi dengan orang lain. Sebaliknya, gunakan pemboleh ubah persekitaran seperti MAILDROPPA_API_KEY.

Gunakan kunci API

Hantar kunci penuh dalam pengepala permintaan HTTP X-API-Key:

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

Jangan hantarnya sebagai token Bearer. Maildroppa memerlukan X-API-Key, bukan Authorization: Bearer ....

API persekitaran pengeluaran dan dokumentasi OpenAPI interaktifnya tersedia di:

https://api.maildroppa.com

Klik “View OpenAPI docs” pada halaman kunci API untuk membuka dokumentasi dalam tab pelayar baharu. Pilih titik akhir di situ untuk menyemak kaedah, laluan, parameter, badan permintaan, jenis respons dan kod status yang mungkin dikembalikan.

Contoh permintaan

Contoh berikut mendapatkan halaman pertama senarai pelanggan e-mel. Ia membaca kunci daripada pemboleh ubah persekitaran dan bukannya memasukkan nilai rahsia terus dalam arahan:

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

Tetapkan pemboleh ubah itu dalam persekitaran selamat tempat integrasi berjalan. Kaedah, laluan, parameter pertanyaan dan badan permintaan yang tepat bergantung pada titik akhir. Salin butiran tersebut daripada dokumentasi OpenAPI, bukan dengan menekanya berdasarkan tindakan yang tersedia dalam aplikasi Maildroppa.

Permintaan dengan badan JSON

Untuk permintaan yang menghantar JSON, sertakan juga:

Content-Type: application/json

Sebagai contoh, struktur asasnya ialah:

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 badan permintaannya ialah ruang letak. Gantikannya dengan titik akhir serta skema permintaan yang didokumenkan.

Akses yang dibenarkan untuk kunci

Kunci hanya berfungsi dengan titik akhir yang menyokong pengesahan kunci API. Halaman atau permintaan yang digunakan secara dalaman oleh aplikasi Maildroppa tidak semestinya sebahagian daripada API awam untuk pelanggan.

Dokumentasi OpenAPI menunjukkan API pelanggan yang disokong. Jika sesuatu laluan tidak didokumenkan untuk penggunaan kunci API, jangan anggap kunci itu boleh mengaksesnya.

Halaman kunci API tidak menawarkan skop atau kotak pilihan kebenaran bagi setiap titik akhir. Oleh itu, kunci akaun semasa perlu dilindungi sebagai kelayakan akses bernilai tinggi, walaupun sesuatu integrasi hanya menggunakan satu titik akhir.

Had kadar permintaan

Kontrak OpenAPI semasa mendokumenkan had kunci API berikut:

• API pelanggan lalai: 300 permintaan seminit dan 2,000 permintaan sejam.
• Events API di /events: 100 permintaan sesaat dengan kapasiti lonjakan sebanyak 500 permintaan.

Had ini dikenakan pada akaun Maildroppa, bukan secara berasingan pada setiap skrip yang berkongsi kuncinya. Oleh itu, beberapa integrasi boleh menggunakan kuota permintaan yang sama.

Apabila Maildroppa mengembalikan 429 Too Many Requests, hentikan penghantaran permintaan baharu dan patuhi pengepala respons Retry-After jika tersedia. Gunakan baris gilir dan sela percubaan semula terkawal (backoff), bukannya memulakan banyak percubaan semula serentak.

Dasar had kadar boleh berubah selagi API masih dalam beta. Semak maklumat di bahagian atas dokumentasi OpenAPI sebelum mereka bentuk integrasi dengan volum permintaan tinggi.

Gunakan kunci untuk permintaan API automasi

Automasi boleh bermula apabila sistem anda menghantar peristiwa tersuai kepada Events API Maildroppa.

Apabila anda mengkonfigurasi pencetus “API request”, Maildroppa menggunakan kunci API akaun yang sama seperti yang diuruskan pada halaman ini. Semasa persediaan pencetus, anda boleh mencipta kunci jika belum ada, serta menyalin permintaan curl yang telah disediakan dan mengandungi kunci penuh.

Ini membawa dua implikasi penting:

• Menggantikan atau memadamkan kunci akaun turut menjejaskan sistem yang menghantar peristiwa tersuai kepada automasi.
• Contoh permintaan automasi yang disalin mengandungi nilai rahsia dalam papan keratan walaupun kunci disamarkan pada skrin.

Sebelum menggantikan atau memadamkan kunci, masukkan setiap pencetus permintaan API dan setiap pengirim peristiwa luaran dalam inventori integrasi anda.

Tetapkan semula atau gantikan kunci API

Gunakan “Rotate API key” apabila anda perlu menetapkan semula atau menggantikan kelayakan akses semasa. Maildroppa mencipta kunci baharu dan membatalkan kunci lama dalam tindakan yang sama.

Lakukan rotasi apabila:

• Kunci mungkin telah terdedah.
• Individu atau penyedia yang mengetahui kunci itu tidak lagi memerlukan akses.
• Dasar keselamatan anda memerlukan penggantian kelayakan akses secara berkala.
• Anda mahu menggantikan kunci yang disimpan di lokasi lama atau tidak selamat.

Klik “Rotate API key” di bawah kunci yang disamarkan. Maildroppa membuka dialog amaran yang menjelaskan bahawa kunci sedia ada tidak lagi boleh digunakan.

Klik “Rotate API key” dalam dialog untuk meneruskan, atau klik “Cancel” untuk mengekalkan kunci semasa.

Tiada tempoh kelonggaran selepas rotasi

Selepas anda mengesahkan rotasi, kunci lama berhenti berfungsi serta-merta. Maildroppa tidak membenarkan kunci lama dan baharu kekal sah pada masa yang sama.

Oleh sebab akaun hanya mempunyai satu kunci, rotasi menjejaskan setiap pelayan, tugas berjadual, integrasi, skrip dan pengirim peristiwa automasi yang menggunakannya.

Ikut urutan ini untuk rotasi yang dirancang:

1. Senaraikan setiap integrasi yang menggunakan kunci semasa.
2. Sediakan akses kepada konfigurasi rahsia dan proses pelaksanaan setiap integrasi.
3. Pilih tempoh penyelenggaraan yang singkat jika akses API tanpa gangguan penting.
4. Klik “Rotate API key”, kemudian sahkan amaran dengan mengklik “Rotate API key” dalam dialog.
5. Klik “Copy” untuk menyalin kunci baharu yang penuh.
6. Gantikan nilai rahsia dalam setiap integrasi dengan segera.
7. Mulakan semula atau laksanakan semula perkhidmatan yang hanya memuatkan rahsia semasa permulaan.
8. Hantar permintaan yang didokumenkan dan tidak membawa kesan berbahaya untuk mengesahkan setiap integrasi.
9. Semak respons 401 Unauthorized daripada perkhidmatan yang terlepas pandang dan masih menggunakan kunci lama.

Jika kunci semasa dipercayai telah dikompromi, gantikannya dengan segera dan terima gangguan singkat yang diperlukan untuk mengemas kini sistem yang sah.

Padam kunci API

Padamkan kunci apabila akaun tidak lagi sepatutnya menerima permintaan yang disahkan menggunakan kunci API.

Klik “Delete API key” di bawah kunci yang disamarkan. Maildroppa membuka dialog amaran yang menjelaskan bahawa kunci akan dialih keluar secara kekal daripada akaun.

Klik “Delete API key” dalam dialog untuk memadamkannya, atau klik “Cancel” untuk mengekalkannya.

Selepas pemadaman:

• Kunci semasa berhenti berfungsi serta-merta.
• Halaman kembali kepada paparan “No API key yet”.
• Integrasi pelayan yang menggunakan kunci yang dipadamkan tidak lagi dapat melalui pengesahan.
• Pengirim permintaan API automasi yang menggunakan kunci itu tidak lagi boleh menghantar peristiwa.

Memadamkan kunci tidak memadamkan pelanggan e-mel, kempen, teg, medan, segmen, automasi atau data akaun lain. Tindakan ini mengalih keluar kelayakan yang digunakan untuk mengakses titik akhir API yang disokong.

Anda boleh mengklik “Create API key” kemudian untuk mencipta kelayakan akses baharu. Nilai yang dipadamkan tidak akan dipulihkan. Setiap integrasi perlu dikemas kini sebelum boleh menggunakan kunci baharu.

Tetapkan semula atau padam: yang mana patut dipilih?

Pilih “Rotate API key” apabila akses API perlu diteruskan dengan kelayakan baharu.

Pilih pemadaman apabila akses API perlu dihentikan sepenuhnya, sekurang-kurangnya buat masa ini.

Kedua-dua tindakan membatalkan kunci semasa serta-merta. Rotasi mencipta kunci pengganti dalam tindakan yang sama; pemadaman pula menjadikan akaun tidak mempunyai kunci.

Cadangan keselamatan

Pastikan panggilan API dibuat pada pelayan anda

Pelayar atau aplikasi mudah alih tidak boleh diharap untuk melindungi rahsia yang dibenamkan di dalamnya. Pengguna boleh memeriksa aplikasi, pengepala permintaan, peta sumber atau trafik rangkaian untuk mendapatkan kunci itu.

Jika laman web atau aplikasi perlu mencetuskan tindakan, hantar permintaan itu terlebih dahulu ke bahagian pelayan (backend) anda sendiri yang memerlukan pengesahan. Biarkan bahagian pelayan itu mengesahkan pengguna dan memanggil Maildroppa menggunakan kunci yang disimpan pada pelayan.

Minimumkan pendedahan kunci

Berikan kunci hanya kepada sistem yang memerlukannya. Jangan edarkannya kepada setiap pembangun atau tampalkannya ke dalam pelbagai fail konfigurasi setempat.

Oleh sebab halaman ini kini mengurus satu kunci untuk seluruh akaun, bukannya beberapa kunci bernama atau berskop, gunakan perkhidmatan integrasi dalaman atau proksi jika beberapa aplikasi memerlukan pengasingan yang lebih ketat antara satu sama lain.

Sembunyikan nilai pengepala permintaan

Konfigurasikan klien HTTP, proksi songsang, alat pemerhatian sistem dan pelapor ralat supaya nilai X-API-Key disembunyikan. Permintaan yang berfungsi dengan betul masih boleh membocorkan kelayakan aksesnya melalui log nyahpepijat.

Kekalkan pengasingan antara persekitaran

Jangan gunakan semula kunci persekitaran pengeluaran dalam pembangunan setempat, kod contoh, tangkapan skrin atau fixtur ujian. Simpan rahsia bagi setiap persekitaran dalam stor rahsia khusus untuk persekitaran tersebut.

Pautan “View OpenAPI docs” secara automatik membawa pengguna persekitaran pengeluaran ke dokumentasi API persekitaran pengeluaran. Sentiasa sahkan nama hos sebelum menghantar kunci sebenar.

Gantikan kunci jika disyaki terdedah

Memadamkan mesej, komit repositori, baris log atau tangkapan skrin tidak membuktikan bahawa tiada sesiapa yang telah menyalin kunci itu. Jika nilai penuh telah terdedah, gantikan kunci tersebut.

Kendalikan ralat API

Gunakan status HTTP dan badan respons yang didokumenkan untuk menentukan tindakan yang perlu diambil oleh integrasi.

Kes lazim termasuk:

• 400 Bad Request — Laluan, parameter atau badan JSON tidak memenuhi kontrak titik akhir. Bandingkan permintaan dengan skema OpenAPI.
• 401 Unauthorized — Pengepala X-API-Key tiada, kosong, tidak sah, telah dipadamkan atau mengandungi nilai lama selepas rotasi.
• 403 Forbidden — Kunci yang telah disahkan tidak dibenarkan menggunakan operasi tersebut.
• 404 Not Found — Laluan atau sumber yang dirujuk tidak wujud dalam akaun ini.
• 429 Too Many Requests — Integrasi telah mencapai had kadar API. Jeda permintaan dan patuhi pengepala Retry-After jika tersedia.
• 5xx — Maildroppa tidak dapat melengkapkan permintaan. Cuba semula operasi yang selamat dengan sela percubaan semula eksponen yang dihadkan dan pengelogan yang tidak menyertakan kunci API.

Jangan cuba semula setiap permintaan yang gagal tanpa menyemak puncanya. Betulkan punca respons 400, 401, 403 dan kebanyakan respons 404 sebelum menghantar permintaan yang sama sekali lagi.

Bagi permintaan yang mengubah data, sahkan tingkah laku percubaan semula dan idempotensi titik akhir sebelum mengulangi permintaan secara automatik. Kegagalan sambungan tidak semestinya bermakna Maildroppa tidak membuat sebarang perubahan.

Penyelesaian masalah

“Create API key” masih dipaparkan

Akaun belum mempunyai kunci pada masa ini. Klik butang sekali dan tunggu sehingga permintaan selesai.

Jika penciptaan gagal, muat semula halaman sebelum mencuba lagi. Kunci akaun mungkin sudah dicipta melalui halaman lain atau persediaan automasi.

Kunci pada halaman kelihatan terlalu pendek

Halaman ini sengaja memaparkan hanya lima aksara pertama dan *****. Klik “Copy” untuk menyalin nilai penuh. Jangan hantar teks yang disamarkan dalam permintaan.

“Copy” tidak bertukar kepada “Copied!”

Pelayar mungkin menyekat akses papan keratan. Pastikan halaman berada dalam tab aktif, benarkan akses papan keratan jika diminta dan klik “Copy” sekali lagi.

Jangan cuba membina semula kunci daripada teks yang disamarkan.

Permintaan mengembalikan 401 Unauthorized

Semak bahawa:

• Nama pengepala tepat seperti berikut: X-API-Key.
• Pengepala mengandungi nilai penuh, tanpa tanda bintang yang dipaparkan.
• Integrasi tidak menghantar Authorization: Bearer sebagai ganti.
• Tiada ruang kosong, tanda petikan atau baris baharu ditambahkan pada nilai rahsia.
• Tiada sesiapa yang menggantikan atau memadamkan kunci akaun.
• Perkhidmatan telah dimulakan semula jika ia hanya membaca pemboleh ubah persekitaran semasa permulaan.
• Permintaan dihantar ke persekitaran API Maildroppa yang betul.

Satu integrasi berfungsi tetapi satu lagi terhenti selepas rotasi

Integrasi kedua mungkin masih menggunakan kunci lama. Tiada tempoh pertindihan antara kunci lama dan baharu. Kemas kini nilai rahsianya dan mulakan semula mana-mana proses yang menyimpan konfigurasi dalam cache.

Halaman OpenAPI berfungsi tetapi titik akhir mengembalikan 403

Bukan semua titik akhir aplikasi menyokong pengesahan kunci API. Gunakan operasi yang didokumenkan untuk API pelanggan dan sahkan keperluan pengesahannya pada halaman OpenAPI.

Permintaan mengembalikan 429 Too Many Requests

Kurangkan lonjakan permintaan, masukkan kerja ke dalam baris gilir dan cuba semula selepas tempoh menunggu yang dikembalikan oleh API. Elakkan terlalu banyak percubaan semula serentak. Jika beberapa aplikasi berkongsi satu kunci akaun, selaraskan jumlah permintaannya kerana semua aplikasi itu berkongsi had API akaun.

Senarai semak persediaan yang disyorkan

Sebelum menggunakan integrasi secara berkala, sahkan bahawa:

• Kunci disimpan hanya dalam konfigurasi rahsia pada pelayan.
• Permintaan menggunakan pengepala X-API-Key.
• Integrasi menggunakan https://api.maildroppa.com dalam persekitaran pengeluaran.
• Setiap kaedah, laluan, parameter dan badan JSON mengikut dokumentasi OpenAPI.
• Log dan laporan ralat menyembunyikan nilai kunci.
• Had masa menunggu dan percubaan semula yang terhad telah dikonfigurasikan.
• Ralat 401, 403, 429 dan ralat pelayan dipantau.
• Pemilik integrasi direkodkan.
• Setiap sistem yang berkongsi kunci akaun dimasukkan dalam pelan rotasi.
• Kunci yang dikompromi boleh digantikan dengan cepat.

Halaman kunci API sengaja direka ringkas, tetapi tindakannya menjejaskan setiap integrasi API yang disambungkan kepada akaun. Cipta kunci hanya apabila diperlukan, simpan pada pelayan yang dipercayai dan rancang rotasi sebagai perubahan kelayakan akses untuk seluruh akaun.