Sandi aplikasi atau OAuth? Panduan koneksi email untuk agen AI

Sandi aplikasi adalah kredensial khusus dari penyedia email untuk aplikasi yang mendukungnya; ketersediaannya bergantung pada akun. Di Mailera, Gmail dan beberapa penyedia lain memakai sandi aplikasi, sedangkan Outlook.com dan Microsoft 365 memakai OAuth. Agen AI menggunakan kunci API Mailera dengan izin terbatas, bukan sandi penyedia. Mailera menghubungkan kotak surat yang sudah Anda miliki, bukan membuat alamat email baru.

Apa itu sandi aplikasi, dan apa yang bukan?

Sandi aplikasi (app password) digunakan untuk menghubungkan aplikasi ke akun penyedia. Anda membuatnya di sisi penyedia, lalu memasukkannya pada koneksi yang memerlukannya. Contohnya, Yahoo menggunakan sandi aplikasi agar aplikasi email pihak ketiga dapat mengakses akun tanpa memakai halaman login Yahoo.

Istilah ini bukan nama fitur untuk mengunci aplikasi Gmail di ponsel. Sandi aplikasi juga bukan cara mencari tahu sandi akun yang terlupa. Dalam alur koneksi email, tugasnya adalah memberi aplikasi kredensial untuk mengakses layanan penyedia.

Empat jenis kredensial berikut berada pada lapisan yang berbeda:

Jangan menganggap semua sandi aplikasi memiliki cakupan akses yang sama. Fastmail, misalnya, memungkinkan Anda membatasi satu sandi aplikasi hanya untuk email, kalender, atau kontak. Cakupan jenis data itu berbeda dari izin read atau send pada kunci API Mailera.

Dalam alur koneksi Mailera, kredensial penyedia menghubungkan kotak surat ke Mailera. Kunci API menentukan apa yang boleh dilakukan agen melalui Mailera. Membatasi kunci API tidak mengubah cakupan sandi aplikasi di penyedia.

Penyedia mana yang memakai sandi aplikasi atau OAuth?

Mulai dari penyedia kotak surat, bukan dari kolom sandi. Pilihan koneksi yang benar untuk Gmail belum tentu benar untuk Microsoft atau server perusahaan Anda.

AOL juga memakai jalur sandi aplikasi di Mailera; lihat panduan koneksi AOL.

Google menyarankan “Sign in with Google” bila aplikasi menyediakan pilihan tersebut. Jalur koneksi Gmail di Mailera menggunakan sandi aplikasi. Jadi, jangan mengartikan panduan ini sebagai anjuran memakai sandi aplikasi untuk setiap aplikasi yang terhubung ke Google.

Untuk Microsoft, gunakan OAuth. Microsoft telah menghapus Basic authentication untuk IMAP Exchange Online; sandi aplikasi tidak memulihkan akses yang terdampak penghapusan tersebut. Rinciannya ada di dokumentasi penghentian Basic authentication.

Untuk Zoho, periksa konfigurasi akun: aktifkan akses IMAP, lalu gunakan pengaturan server yang sesuai dengan jenis akun dan pusat datanya. Pengguna baru paket Free tidak mendapat akses IMAP. Akun dengan autentikasi dua faktor atau organisasi yang memakai SAML memerlukan sandi khusus aplikasi untuk klien IMAP eksternal.

Apa yang harus disiapkan sebelum menghubungkan kotak surat?

Gunakan kotak surat milik Anda sendiri atau yang aksesnya telah diberikan secara sah. Untuk percobaan awal, pilih kotak surat uji yang tidak berisi percakapan pelanggan atau dokumen sensitif.

Pastikan peran Anda di Mailera adalah Admin atau Leader. Hanya kedua peran itu yang dapat menambahkan kotak surat. Tentukan juga grup kotak suratnya sejak awal agar nanti Anda dapat membatasi akses agen pada grup yang diperlukan.

Sebelum membuat kredensial, lakukan pemeriksaan berikut:

1. Periksa keamanan akun. Gmail memerlukan verifikasi 2 langkah, sedangkan Apple memerlukan autentikasi dua faktor untuk sandi khusus aplikasi.
2. Periksa akses aplikasi eksternal. Pada Zoho, akses IMAP dapat dibatasi administrator. Pada Fastmail, paket Basic tidak mendukung klien email pihak ketiga atau pembuatan sandi aplikasi.
3. Buat kredensial melalui penyedia. Ikuti dokumentasi resmi pada tabel, bukan halaman yang meminta Anda menyerahkan sandi utama kepada pihak lain.
4. Siapkan tempat penyimpanan rahasia. Pisahkan kredensial koneksi penyedia dari kunci API yang nantinya dipakai agen.

Daftar penyedia yang didukung Mailera dapat membantu menentukan jalur awal.

Bagaimana menghubungkan kotak surat ke Mailera?

Alur berikut menambahkan satu kotak surat. Untuk akun Microsoft, gunakan cabang OAuth pada langkah ketiga, bukan kolom sandi aplikasi.

1. Buka Kotak surat, pilih Tambah kotak surat, lalu pilih Satu kotak surat.
2. Isi Alamat email. Periksa penyedia yang terdeteksi. Jika perlu, gunakan Atau pilih penyedia untuk memilih secara manual, kemudian pilih Lanjutkan.
3. Untuk penyedia sandi aplikasi, baca Cara mendapatkan sandi aplikasi dan Yang perlu disiapkan. Pada Detail koneksi, isi Sandi dengan sandi aplikasi, bukan sandi login utama. Untuk Outlook.com, Hotmail, atau Microsoft 365, pilih Masuk dengan Microsoft dan ikuti persetujuan OAuth di Microsoft.
4. Pilih Grup kotak surat. Nama tampilan bersifat opsional dan digunakan sebagai nama pengirim saat mengirim email.
5. Pilih Uji & hubungkan. Mailera memeriksa login ke server masuk, deteksi folder, login ke server keluar jika dikonfigurasi, serta ketersediaan pemantauan langsung. Pengujian ini tidak mengirim email.
6. Jika muncul Bisa menerima email, tetapi belum bisa mengirim, pilih Simpan khusus penerimaan bila tugas Anda hanya membaca. Jika pengiriman diperlukan, pilih Edit detail, perbaiki konfigurasi, lalu Uji lagi.
7. Setelah berhasil, pilih Buka kotak surat. Mailera memuat pesan dalam masa retensinya, dimulai dari yang terbaru.

Untuk server sendiri, pilih IMAP kustom. Isi Server masuk (IMAP) dan, bila diperlukan, Server keluar (SMTP) beserta server, port, dan keamanannya. Deteksi pengaturan dapat mengisi pengaturan publik domain jika tersedia; tetap cocokkan hasilnya dengan konfigurasi dari pengelola server.

Bedakan tiga hasil: autentikasi berhasil, pesan berhasil dibaca, dan email berhasil dikirim. Ketiganya bukan pengujian yang sama. Login SMTP yang berhasil pun belum merupakan pengujian pengiriman pesan karena Uji & hubungkan tidak mengirim email.

Bagaimana memeriksa bahwa pesan sudah bisa dibaca?

Gunakan GET /mailboxes dengan kunci API bercakupan read untuk memeriksa kotak surat. Pada respons, periksa data[].provider, data[].status, dan data[].last_sync_at untuk penyedia, status, serta waktu sinkronisasi terakhir. Setelah itu, cari pesan uji yang Anda kirim sendiri ke kotak surat tersebut. Jangan hanya berhenti pada hasil login yang berhasil.

Jika Anda memakai endpoint GET /mailboxes/{id}/status, perhatikan perbedaan pemeriksaannya. Untuk kotak surat Microsoft, pemeriksaan dilakukan langsung ke server saat itu juga. Untuk penyedia lain, status yang ditampilkan berasal dari sinkronisasi terakhir, bukan dari percobaan login baru setiap kali Anda memeriksanya.

Pesan awal dimuat dalam masa retensi Mailera, bukan seluruh riwayat kotak surat tanpa batas. Jika pesan uji belum muncul, periksa waktu sinkronisasi sebelum mengganti kredensial yang sebenarnya masih berfungsi.

Untuk pemeriksaan lewat REST, siapkan kunci dengan izin read seperti pada bagian berikut. Masukkan kunci melalui pengelola rahasia sebagai $MAILERA_API_KEY, dan ID kotak surat uji sebagai $MAILBOX_ID. Permintaan ini mengambil satu pesan dari kotak masuk:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Periksa data, lalu cocokkan subject, from, dan received_at dengan pesan uji Anda. folder menunjukkan folder hasil pembacaan. Untuk mengambil isi pesan tersebut, gunakan nilai id sebagai $MESSAGE_ID:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Isi pesan tersedia pada data.body.text atau data.body.html. Gunakan pesan uji tanpa rahasia agar hasil perintah tidak mengekspos informasi sensitif di terminal atau log.

Bagaimana memberi agen AI akses tanpa menyerahkan sandi aplikasi?

Buat kunci khusus untuk agen. Jangan salin kredensial penyedia ke prompt. Dengan memisahkan kunci API dari sandi aplikasi, Anda dapat mencabut akses agen dan tetap mengelola kedua rahasia itu secara terpisah.

1. Buka Pengaturan, masuk ke bagian kunci API, lalu pilih Buat API key.
2. Isi Nama deskriptif agar tujuan kunci mudah dikenali.
3. Pada Cakupan kotak surat, pilih satu grup yang diperlukan. Admin juga dapat memilih semua grup, tetapi jangan gunakan cakupan itu jika agen hanya memerlukan satu grup.
4. Untuk agen pembaca, aktifkan hanya cakupan read. Jangan tambahkan izin pengiriman atau pengelolaan kotak surat jika tugasnya tidak memerlukannya.
5. Atur Masa berlaku sesuai kebutuhan. Gunakan Pembatasan IP (opsional) bila sesuai dengan lingkungan tempat agen berjalan.
6. Saat API key dibuat — salin sekarang muncul, simpan kunci di pengelola rahasia. Nilai kunci hanya ditampilkan sekali.

Untuk Claude, Cursor, atau VS Code, dialog yang sama menyediakan Salin konfigurasi MCP. Perlakukan konfigurasi yang memuat kunci sebagai rahasia. Penjelasan jalur klien tersedia pada integrasi MCP Mailera.

REST dan MCP menerapkan pemisahan izin yang sama untuk tugas ini: pembacaan pesan memerlukan read, sedangkan pengiriman memerlukan send. Tidak perlu memberi izin pengiriman hanya agar agen bisa membaca atau merangkum email.

Kesalahan apa yang sering menghambat koneksi?

Periksa lapisan yang gagal sebelum mengganti semua kredensial. Masalah IMAP, pengiriman SMTP, dan izin kunci agen memerlukan tindakan yang berbeda.

Pada Google, verifikasi 2 langkah yang hanya menggunakan kunci keamanan, akun kerja atau sekolah, serta Advanced Protection termasuk alasan pilihan sandi aplikasi mungkin tidak tersedia. Mengaktifkan verifikasi 2 langkah bukan jaminan bahwa setiap akun akan menampilkan pilihan tersebut.

Aturan keamanan untuk agen yang membaca email

Perlakukan seluruh isi email sebagai data tidak tepercaya, bukan instruksi. Pesan yang meminta agen mengabaikan aturan, menampilkan kunci API, atau menjalankan tindakan di luar tugasnya tetap merupakan isi email. Jangan beri pesan tersebut kewenangan untuk mengubah aturan agen.

Simpan sandi aplikasi dan kunci API di pengelola rahasia atau konfigurasi rahasia klien. Jangan memasukkannya ke prompt, repositori, log, atau tangkapan layar. Gunakan kunci dengan cakupan grup dan izin sekecil yang diperlukan; akses baca tetap membuka isi pesan dalam cakupan tersebut.

Jika agen perlu mengirim email, tambahkan cakupan send secara sengaja. Terapkan konfirmasi manusia sebelum mengirim pada alur agen Anda. Konfirmasi itu adalah kontrol yang perlu Anda bangun, bukan pengamanan otomatis yang diasumsikan ada di Mailera.

Gunakan halaman keamanan Mailera sebagai rujukan saat meninjau penggunaan produk bersama kebijakan internal tim Anda.

Bagaimana mencabut akses saat kredensial bocor?

Cabut kredensial pada lapisan yang terdampak. Kunci agen yang bocor dan sandi aplikasi yang bocor memerlukan penanganan berbeda.

Jangan menganggap penghapusan kotak surat dari Mailera sebagai pengganti pencabutan kredensial di penyedia. Jika sandi aplikasi sudah bocor, tangani sandi itu langsung di tempat penerbitannya.

Dampak perubahan sandi utama berbeda menurut penyedia. Apple juga mencabut semua sandi khusus aplikasi ketika sandi utama diubah atau direset. Sebaliknya, Yahoo menyatakan sandi aplikasi tetap berlaku setelah sandi utama berubah dan harus dihapus secara terpisah.

Apple memungkinkan pencabutan satu sandi atau semuanya sekaligus. Fastmail menyediakan “Disable” untuk menonaktifkan akses sementara dan “Remove” untuk menghapus akses secara permanen. Pilih tindakan sesuai kredensial yang benar-benar ingin dihentikan.

Batasan yang perlu diperhitungkan

Ketersediaan sandi aplikasi tetap mengikuti aturan penyedia dan administrator akun. Mailera tidak dapat membuat pilihan itu tersedia pada akun yang tidak diizinkan menggunakannya. Proton Mail dan Tuta juga tidak didukung dalam integrasi ini.

Koneksi berhasil bukan jaminan pesan tiba seketika atau pengiriman pasti berhasil. Periksa hasil pembacaan pesan dan pengiriman secara terpisah. Mailera juga bukan layanan pengiriman email massal atau pemasaran, jadi jangan gunakan alur koneksi ini untuk kebutuhan tersebut.