Cipta dan Urus Kunci API Anda

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

Halaman Kunci API memberikan sistem luaran akses yang disahkan kepada titik akhir API Maildroppa yang disokong dalam akaun anda.

Anda boleh mencipta satu kunci API, menyalin nilai rahsia lengkapnya, menetapkannya semula dengan selamat melalui putaran, atau memadamkannya apabila tidak lagi diperlukan. Kunci akaun yang sama boleh digunakan oleh integrasi sisi pelayan dan pencetus permintaan API dalam Automasi Maildroppa.

Kunci API mewakili akaun Maildroppa anda. Kendalikannya seperti kata laluan: sesiapa yang memperoleh kunci tersebut boleh memanggil titik akhir API yang tersedia untuk kunci itu sehingga anda memutarkan atau memadamkannya.

Untuk Apa Kunci API Digunakan

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

Contoh lazim termasuk:

• Menyegerakkan pelanggan dengan CRM, kedai, sistem keahlian atau pangkalan data dalaman.
• Mencipta atau mengemas kini pelanggan daripada aplikasi sisi pelayan.
• Membaca atau mengurus tag, medan, nilai medan dan segmen melalui titik akhir yang disokong.
• Menghantar acara tersuai kepada pencetus permintaan API dalam Automasi.
• Menghantar Mesej E-mel transaksional melalui API.
• Mengurus langganan webhook berasaskan API.

Kunci API bertujuan untuk komunikasi pelayan-ke-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”. Gunakan dokumentasi OpenAPI yang dipautkan sebagai sumber untuk titik akhir, badan permintaan, parameter dan skema respons yang kini disokong oleh API.

Membuka 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”.
• Keadaan kosong dan butang “Create API key” apabila tiada kunci wujud.
• Perwakilan bertopeng bagi kunci semasa apabila kunci wujud.
• Butang “Copy” yang menyalin kunci lengkap.
• 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 aplikasi, persekitaran atau ahli pasukan tertentu.

Mencipta Kunci API

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

Maildroppa mencipta kunci serta-merta. Tiada dialog pengesahan untuk penciptaan pertama ini. Semasa permintaan sedang berjalan, butang berubah kepada “Creating API key” dan halaman melumpuhkan sementara tindakan kunci selanjutnya.

Selepas kunci dicipta:

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

Jika kunci lain sudah wujud untuk akaun tersebut, Maildroppa tidak mencipta kunci kedua. Gunakan kunci sedia ada atau putarkannya.

Memahami Kunci Bertopeng

Halaman ini tidak memaparkan rahsia lengkap sebagai teks biasa. Ia menunjukkan lima aksara pertama diikuti lima tanda bintang, contohnya:

a1b2c*****

Ini hanyalah topeng visual. Tanda bintang tidak mewakili panjang sebenar kunci, dan nilai bertopeng tidak boleh digunakan untuk permintaan API.

Klik “Copy” untuk menulis kunci semasa yang lengkap ke papan keratan anda. Selepas penyalinan berjaya, butang berubah seketika kepada “Copied!”.

Kunci kekal bertopeng apabila anda kembali ke halaman, tetapi “Copy” terus menyalin nilai semasa yang lengkap. Oleh itu, anda tidak perlu memutarkan kunci yang sah semata-mata kerana anda tidak menyimpannya semasa penciptaan.

Menyimpan Kunci dengan Selamat

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

Lokasi yang sesuai termasuk:

• Pengurus rahsia terurus.
• Konfigurasi persekitaran pelayan yang dilindungi.
• Rahsia penggunaan yang disulitkan.
• Pengurus kata laluan yang digunakan untuk pemulihan operasi.

Jangan simpan kunci dalam:

• JavaScript sisi pelayar atau himpunan frontend lain yang boleh dimuat turun.
• Fail kod sumber awam atau peribadi yang dihantar ke repositori.
• URL atau parameter pertanyaan.
• Dokumentasi awam, tangkapan skrin, mesej sokongan atau penjejak isu.
• Log aplikasi dikongsi, acara analitik atau laporan ralat.
• Hamparan yang tidak disulitkan atau sembang pasukan biasa.

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

Menggunakan Kunci API

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

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

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

API 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 sana untuk menyemak kaedah, laluan, parameter, badan permintaan, jenis respons dan kod status yang mungkin.

Contoh Permintaan

Contoh berikut mendapatkan halaman pertama pelanggan. Ia membaca kunci daripada pemboleh ubah persekitaran dan bukannya meletakkan 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 tersebut dalam persekitaran selamat tempat integrasi berjalan. Kaedah, laluan, parameter pertanyaan dan badan yang tepat bergantung pada titik akhir. Salin butiran tersebut daripada dokumentasi OpenAPI dan bukannya meneka 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 badannya ialah ruang letak. Gantikannya dengan titik akhir yang didokumenkan dan skema permintaan yang didokumenkan.

Perkara yang Boleh Diakses oleh Kunci

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

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

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

Had Kadar

Kontrak OpenAPI semasa mendokumenkan had kunci API berikut:

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

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

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

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

Menggunakan Kunci untuk Permintaan API Automasi

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

Apabila anda mengkonfigurasi pencetus “API request”, Maildroppa menggunakan kunci API akaun yang sama yang diuruskan pada halaman ini. Persediaan pencetus boleh mencipta kunci apabila tiada kunci wujud dan boleh menyalin permintaan curl yang disediakan, termasuk kunci lengkap.

Ini mempunyai dua akibat penting:

• Memutarkan atau memadam kunci akaun turut menjejaskan sistem yang menghantar acara tersuai kepada Automasi.
• Contoh permintaan Automasi yang disalin mengandungi rahsia dalam papan keratan walaupun kunci bertopeng pada skrin.

Sebelum memutarkan atau memadam kunci, masukkan setiap pencetus permintaan API dan setiap penghantar acara luaran dalam inventori integrasi anda.

Menetapkan Semula atau Menggantikan Kunci API

Gunakan “Rotate API key” apabila anda perlu menetapkan semula atau menggantikan kelayakan semasa. Maildroppa mencipta kunci baharu dan membatalkan kunci sebelumnya sebagai sebahagian daripada tindakan yang sama.

Gunakan putaran apabila:

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

Klik “Rotate API key” di bawah kunci bertopeng. 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.

Putaran Tiada Tempoh Ihsan

Selepas anda mengesahkan putaran, kunci lama berhenti berfungsi serta-merta. Maildroppa tidak mengekalkan kunci lama dan baharu sebagai sah pada masa yang sama.

Oleh sebab akaun hanya mempunyai satu kunci, putaran menjejaskan setiap pelayan, tugas berjadual, integrasi, skrip dan penghantar acara Automasi yang menggunakannya.

Gunakan urutan ini untuk putaran yang dirancang:

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

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

Memadam Kunci API

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

Klik “Delete API key” di bawah kunci bertopeng. 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 keadaan “No API key yet”.
• Integrasi pelayan yang menggunakan kunci yang dipadam tidak lagi boleh mengesahkan diri.
• Penghantar permintaan API Automasi yang menggunakan kunci tersebut tidak lagi boleh menghantar acara.

Memadam kunci tidak memadam pelanggan, kempen, tag, medan, segmen, Automasi atau data akaun lain. Ia mengalih keluar kelayakan yang digunakan untuk mengakses titik akhir API yang disokong.

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

Menetapkan Semula atau Memadam: Mana yang 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. Putaran mencipta pengganti sebagai sebahagian daripada tindakan yang sama; pemadaman meninggalkan akaun tanpa kunci.

Cadangan Keselamatan

Kekalkan Panggilan API pada Pelayan Anda

Pelayar atau aplikasi mudah alih tidak boleh menyimpan rahsia terbenam dengan boleh dipercayai. Pengguna boleh memeriksa aplikasi, pengepala permintaan, peta sumber atau trafik rangkaian dan mengekstrak kunci.

Jika laman web atau aplikasi perlu mencetuskan tindakan, hantar permintaan itu kepada backend anda sendiri yang disahkan terlebih dahulu. Biarkan backend mengesahkan pengguna dan memanggil Maildroppa dengan kunci yang disimpan pada pelayan.

Gunakan Pendedahan Minimum yang Mungkin

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

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

Sembunyikan Pengepala Permintaan

Konfigurasikan klien HTTP, proksi terbalik, alat kebolehlihatan dan pelapor ralat untuk menyembunyikan X-API-Key. Permintaan boleh berfungsi dengan betul tetapi masih membocorkan kelayakannya melalui pengelogan nyahpepijat.

Asingkan Persekitaran Berbeza

Jangan gunakan semula kunci pengeluaran dalam pembangunan tempatan, kod contoh, tangkapan skrin atau lekapan ujian. Simpan rahsia khusus persekitaran dalam stor rahsia khusus persekitaran.

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

Putarkan Selepas Sebarang Pendedahan yang Disyaki

Memadam mesej, komit repositori, baris log atau tangkapan skrin tidak membuktikan bahawa tiada sesiapa menyalin kunci tersebut. Jika nilai lengkap telah terdedah, putarkannya.

Mengendalikan Ralat API

Gunakan status HTTP dan badan respons yang didokumenkan untuk menentukan tindakan yang patut dilakukan 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, dipadam atau mengandungi nilai lama selepas putaran.
• 403 Forbidden — Kunci yang 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 apabila tersedia.
• 5xx — Maildroppa tidak dapat melengkapkan permintaan. Cuba semula operasi selamat dengan backoff eksponen terhad dan pengelogan yang tidak menyertakan kunci API.

Jangan cuba semula setiap kegagalan secara membuta tuli. Betulkan respons 400, 401, 403 dan kebanyakan respons 404 sebelum menghantar permintaan yang sama sekali lagi.

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

Penyelesaian Masalah

“Create API key” Masih Kelihatan

Tiada kunci wujud dalam akaun pada masa ini. Klik butang sekali dan tunggu sehingga permintaan selesai.

Jika penciptaan gagal, muat semula halaman sebelum mencuba lagi. Halaman lain atau persediaan Automasi mungkin telah mencipta kunci akaun tersebut.

Kunci pada Halaman Kelihatan Terlalu Pendek

Halaman sengaja hanya menunjukkan lima aksara pertama dan *****. Klik “Copy” untuk menyalin nilai lengkap. Jangan hantar teks bertopeng dalam permintaan.

“Copy” Tidak Berubah kepada “Copied!”

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

Jangan cuba membina semula kunci daripada teks bertopeng.

Permintaan Mengembalikan 401 Unauthorized

Semak bahawa:

• Nama pengepala ialah tepat X-API-Key.
• Pengepala mengandungi nilai lengkap, tanpa tanda bintang yang kelihatan.
• Integrasi tidak menghantar Authorization: Bearer sebaliknya.
• Ruang kosong, tanda petikan atau baris baharu tidak ditambahkan pada rahsia.
• Tiada sesiapa memutarkan atau memadam 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 Berhenti Selepas Putaran

Integrasi kedua mungkin masih menggunakan kunci lama. Tiada tempoh pertindihan. Kemas kini rahsianya dan mulakan semula sebarang proses yang menyimpan konfigurasi dalam cache.

Halaman OpenAPI Berfungsi tetapi Titik Akhir Mengembalikan 403

Tidak setiap 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 kelewatan yang dikembalikan oleh API. Elakkan ribut percubaan semula selari. Jika beberapa aplikasi berkongsi satu kunci akaun, selaraskan jumlah permintaan kerana mereka berkongsi had API akaun.

Senarai Semak Persediaan yang Disyorkan

Sebelum menggunakan integrasi secara berkala, sahkan bahawa:

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

Halaman Kunci API sengaja kecil, tetapi tindakannya menjejaskan setiap integrasi API yang disambungkan kepada akaun. Cipta kunci hanya apabila diperlukan, simpan pada pelayan dipercayai dan rancang putaran sebagai perubahan kelayakan seluruh akaun.