---
title: "Sandi aplikasi atau OAuth? Panduan koneksi email untuk agen AI"
description: "Pahami sandi aplikasi, syarat Gmail dan penyedia lain, kapan memakai OAuth, serta cara memberi agen AI akses email lewat kunci API Mailera."
url: https://mailera.app/id/blog/sandi-aplikasi-oauth-email-agen-ai
published: 2026-10-25
updated: 2026-10-25
---

# Sandi aplikasi atau OAuth? Panduan koneksi email untuk agen AI

Pilih metode koneksi sesuai penyedia email, lalu berikan akses kepada agen lewat kunci API Mailera. Sandi aplikasi penyedia tetap terpisah dari kredensial agen.

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:

| Kredensial | Penerbit | Dipakai di mana? | Pengelolaan akses |
| --- | --- | --- | --- |
| Sandi akun utama | Penyedia akun | Login utama ke akun | Kelola di penyedia; dampak perubahan terhadap sandi aplikasi berbeda menurut penyedia |
| Sandi aplikasi | Penyedia email | Koneksi aplikasi yang memakai metode ini | Cabut sandi aplikasi di penyedia |
| Token OAuth | Platform identitas Microsoft | Koneksi Microsoft di Mailera memakai OAuth melalui Microsoft Graph | Cabut akses lewat sesi Microsoft Anda, atau hubungkan kembali kotak surat di Mailera |
| Kunci API Mailera | Mailera | Permintaan REST atau MCP dari aplikasi dan agen | Cabut kunci API di Mailera |

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](https://mailera.app/id/product), 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.

![Dua lapisan akses: kotak surat terhubung ke Mailera dengan kredensial penyedia, dan agen mengakses Mailera dengan kunci API.](https://mailera.app/media/e95a72bd7a275ce0/sandi-aplikasi-atau-oauth-panduan-koneksi-email-untuk-agen-id-1200.jpg)
_Kredensial penyedia dan kunci agen digunakan pada lapisan yang berbeda._

## 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.

| Penyedia | Jalur koneksi Mailera | Syarat yang perlu diperiksa | Dokumentasi dan panduan koneksi |
| --- | --- | --- | --- |
| Gmail / Google Workspace | Sandi aplikasi | Verifikasi 2 langkah dan kebijakan akun organisasi | [Bantuan Google](https://support.google.com/accounts/answer/185833?hl=id); [koneksi Gmail](https://mailera.app/id/providers/gmail) |
| Yahoo | Sandi aplikasi | Kelayakan pembuatan sandi aplikasi pada akun | [Bantuan Yahoo](https://help.yahoo.com/kb/SLN15241.html); [koneksi Yahoo](https://mailera.app/id/providers/yahoo) |
| iCloud | Sandi khusus aplikasi | Autentikasi dua faktor pada Akun Apple | [Bantuan Apple](https://support.apple.com/en-us/102654); [koneksi iCloud](https://mailera.app/id/providers/icloud) |
| Zoho | Sandi aplikasi | Akses IMAP, paket, kebijakan administrator, dan server akun | [Dokumentasi IMAP Zoho](https://www.zoho.com/mail/help/imap-access.html); [koneksi Zoho](https://mailera.app/id/providers/zoho) |
| Fastmail | Sandi aplikasi | Paket yang mendukung klien pihak ketiga; paket Basic tidak mendukungnya | [Dokumentasi Fastmail](https://www.fastmail.help/hc/en-us/articles/360058752854-App-passwords); [koneksi Fastmail](https://mailera.app/id/providers/fastmail) |
| Outlook.com / Hotmail / Microsoft 365 | OAuth melalui Microsoft Graph | Ikuti login dan persetujuan Microsoft | [Autentikasi Microsoft Graph](https://learn.microsoft.com/en-us/graph/auth-v2-user); [koneksi Microsoft](https://mailera.app/id/providers/microsoft) |
| IMAP khusus | Konfigurasi server sendiri | Server, port, keamanan, dan metode autentikasi yang ditetapkan pengelola | [Koneksi IMAP khusus](https://mailera.app/id/providers/imap) |

AOL juga memakai jalur sandi aplikasi di Mailera; lihat [panduan koneksi AOL](https://mailera.app/id/providers/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](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/deprecation-of-basic-authentication-exchange-online).

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](https://mailera.app/id/providers) 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.

![Formulir Detail koneksi Mailera dengan kolom Sandi dan tombol Uji & hubungkan.](https://mailera.app/media/e1a73d66eb389fda/sandi-aplikasi-atau-oauth-panduan-koneksi-email-untuk-agen-id-1200.jpg)
_Untuk penyedia sandi aplikasi, isi kolom Sandi dengan kredensial aplikasi dari penyedia._

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:

```bash
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`:

```bash
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.

![Pengaturan kunci API Mailera untuk satu grup kotak surat dengan izin baca tanpa izin pengiriman.](https://mailera.app/media/0ebeb78eaf3550c5/sandi-aplikasi-atau-oauth-panduan-koneksi-email-untuk-agen-id-1200.jpg)
_Agen pembaca cukup diberi izin read pada grup kotak surat yang diperlukan._

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](https://mailera.app/id/mcp).

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.

| Gejala | Pemeriksaan awal | Tindakan berikutnya |
| --- | --- | --- |
| Pilihan sandi aplikasi Gmail tidak muncul | Verifikasi 2 langkah, akun organisasi, penggunaan kunci keamanan saja, atau Advanced Protection | Cocokkan kondisi akun dengan [penjelasan Google](https://support.google.com/accounts/answer/185833?hl=id); untuk akun organisasi, tanyakan kebijakannya kepada administrator |
| Autentikasi ditolak | Alamat email, sandi utama yang keliru dimasukkan, atau sandi aplikasi yang sudah dicabut | Periksa kredensial pada penyedia dan gunakan sandi aplikasi yang sesuai |
| Login web berhasil, tetapi IMAP gagal | Akses IMAP, paket, kebijakan organisasi, server dan keamanan | Periksa konfigurasi khusus akun; pada Zoho, gunakan server sesuai jenis akun dan pusat data |
| Pesan bisa dibaca, tetapi pengiriman gagal | Konfigurasi dan login server SMTP | Perbaiki server keluar atau pilih **Simpan khusus penerimaan** |
| Microsoft gagal dengan sandi aplikasi | Metode koneksi yang dipilih | Kembali ke **Masuk dengan Microsoft** dan gunakan OAuth |
| Status baik, tetapi pesan belum muncul | Waktu sinkronisasi terakhir dan folder pesan | Periksa sinkronisasi serta cari pesan uji pada folder yang sesuai |
| Agen gagal membaca, tetapi kotak surat terhubung | Cakupan grup dan izin kunci API | Pastikan kotak surat berada dalam grup yang diizinkan dan kunci memiliki `read` |

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](https://mailera.app/id/security) 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.

| Yang terdampak | Tindakan |
| --- | --- |
| Kunci API agen | Cabut kunci di Mailera. Permintaan yang memakai kunci itu langsung ditolak. Buat pengganti dengan izin minimum dan perbarui rahasia pada klien agen |
| Sandi aplikasi penyedia | Cabut sandi aplikasi di penyedia, lalu buat kredensial pengganti untuk koneksi yang masih diperlukan |
| Token OAuth Microsoft | Hubungkan kembali kotak surat di Mailera menggunakan **Masuk dengan Microsoft** agar token lama tergantikan, atau tinjau akses aplikasi pada akun Microsoft Anda |

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.

**Hubungkan kotak surat pertama Anda dalam 2 menit** — Tambahkan kotak surat Outlook, Gmail, atau IMAP dan baca pesan email di aplikasi atau melalui API. [Hubungkan kotak surat](https://mailera.app/auth?mode=signup)