Cara Mengambil Kode OTP Gmail lewat API Mailera

Apa bedanya Gmail API dan endpoint OTP Mailera?

OTP yang dibahas di sini adalah kode verifikasi dari aplikasi uji Anda yang dikirim ke Gmail. Bukan kode keamanan untuk masuk ke akun Google. Gunakan hanya aplikasi dan kotak surat yang Anda miliki atau kelola dengan izin.

Ada dua jalur untuk membaca kode verifikasi Gmail: mengakses Gmail API langsung atau menghubungkan Gmail ke Mailera, lalu memakai API Mailera.

Menurut dokumentasi daftar pesan Gmail API, users.messages.list hanya mengembalikan id dan threadId; isi pesan baru didapat lewat messages.get, dan parameter pencarian q memakai format Gmail sendiri — berbeda dari parameter endpoint OTP Mailera. Jangan menyalin nama parameter dari satu API ke API lainnya.

Jika Anda sudah membangun integrasi langsung, gunakan cakupan otorisasi Gmail API sesuai kebutuhan. Untuk jalur Mailera, halaman pengembang menjelaskan akses API, sedangkan panduan membaca OTP dari kotak sendiri membahas alur umumnya.

Apa yang perlu disiapkan sebelum menghubungkan Gmail?

Siapkan kotak Gmail khusus pengujian, aplikasi yang mengirim email verifikasi, dan akun Mailera dengan peran Admin atau Leader. Kedua peran tersebut dapat menambahkan kotak surat.

Koneksi Gmail dan Google Workspace di Mailera memakai sandi aplikasi (app password), bukan sandi masuk akun Google. Google mensyaratkan verifikasi 2 langkah untuk memakai sandi aplikasi. Ikuti bantuan sandi aplikasi Google dan panduan verifikasi 2 langkah.

Opsi sandi aplikasi mungkin tidak muncul pada akun yang hanya memakai kunci keamanan untuk verifikasi 2 langkah, akun organisasi, atau akun dengan Advanced Protection. Untuk Google Workspace, periksa izin administrator. Jika pengaturan verifikasi 2 langkah dibatasi organisasi, hubungi administrator; jangan menonaktifkan perlindungan akun agar koneksi berhasil.

Google merekomendasikan "Sign in with Google" untuk aplikasi yang mendukungnya, tetapi rekomendasi itu berlaku untuk login OAuth, bukan untuk koneksi IMAP pihak ketiga seperti Mailera. Jalur koneksi Gmail di Mailera memakai sandi aplikasi. Pembahasan sandi aplikasi untuk kotak surat agen membantu membedakan kredensial koneksi dari akses aplikasi pemanggil.

Pisahkan ketiga rahasia berikut:

Jangan memasukkan sandi aplikasi Google ke header API Mailera, atau memakai OTP sebagai sandi koneksi.

Bagaimana menghubungkan Gmail dan membatasi akses API?

1. Buka Kotak surat → Tambah kotak surat, lalu pilih Satu kotak surat. Isi Alamat email dengan alamat Gmail uji. Periksa penyedia yang terdeteksi, atau pilih Gmail melalui Atau pilih penyedia, kemudian tekan Lanjutkan.
2. Pada Detail koneksi, isi Sandi dengan sandi aplikasi Google. Pilih Grup kotak surat khusus pengujian agar akses API nantinya tidak mencakup kotak lain.
3. Tekan Uji & hubungkan. Pengujian koneksi ini tidak mengirim email. Jika penerimaan berhasil tetapi pengiriman gagal, tersedia Simpan khusus penerimaan; tugas membaca OTP tidak memerlukan pengiriman melalui Mailera.
4. Setelah terhubung, tunggu pemuatan awal dan periksa pesan uji melalui Kotak masuk terpadu. Mailera memuat pesan dalam masa retensinya, mulai dari yang terbaru.

Status koneksi bukan bukti bahwa email tertentu sudah diterima. Untuk Gmail, GET /mailboxes/{id}/status menggunakan hasil sinkronisasi terakhir, bukan pemeriksaan masuk langsung saat permintaan dibuat. Frekuensi pemeriksaan latar belakang juga mengikuti aktivitas kotak surat.

Berikutnya, buka Pengaturan, masuk ke bagian kunci API, lalu pilih Buat API key. Isi Nama deskriptif, batasi Cakupan kotak surat ke grup uji, dan aktifkan hanya izin read. Atur Masa berlaku sesuai durasi penggunaan.

Saat muncul API key dibuat — salin sekarang, simpan nilainya di penyimpanan rahasia Anda. Kunci hanya ditampilkan sekali. Simpan nilainya dalam variabel lingkungan shell $MAILERA_API_KEY, bukan sebagai teks tetap dalam repositori.

Bagaimana meminta kode OTP yang sesuai dengan pengujian?

1. Temukan ID kotak Gmail yang benar

Jalankan permintaan daftar kotak surat dari terminal lokal, bukan dari job CI yang keluarannya tersimpan ke log bersama:

curl --silent --show-error \
  'https://mailera.app/api/public/v1/mailboxes' \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Pada array data, cocokkan email dengan alamat Gmail uji, lalu ambil id dari entri tersebut. Simpan sebagai $MAILBOX_ID. Jangan mengambil entri pertama secara otomatis: kunci berlingkup grup dapat melihat lebih dari satu kotak surat. Jika daftar memiliki halaman lanjutan, gunakan limit dan offset untuk menemukannya.

2. Mulai sesi uji sebelum meminta kode

Catat waktu mulai pengujian, lalu minta aplikasi Anda mengirim email verifikasi ke kotak tersebut. Jika Anda mengendalikan templat email, gunakan penanda sesi pada subjek agar pesan dari dua pengujian tidak mudah tertukar.

Untuk pengujian paralel, jangan mengandalkan kata “terbaru” sebagai satu-satunya pembeda. Pesan terbaru bisa berasal dari sesi lain yang memakai kotak surat sama.

3. Panggil endpoint OTP dengan filter

Endpoint GET /mailboxes/{id}/otp memerlukan izin read dan menerima parameter berikut:

Contoh berikut memakai rentang lima menit sebagai pilihan pengujian, bukan nilai bawaan. Ganti alamat contoh dan subjek dengan nilai yang digunakan aplikasi Anda:

curl --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=verifikasi@example.com' \
  --data-urlencode 'subject=Verifikasi aplikasi uji' \
  --data-urlencode 'since_minutes=5'

Perintah ini menampilkan respons ke terminal. Jangan menjalankannya dalam pekerjaan CI yang merekam seluruh keluaran. Saat mengintegrasikan pembaca OTP, tangani respons dalam proses aplikasi tanpa mencetak kode atau isi email. Rujuk dokumentasi API Mailera untuk implementasi pemanggilnya.

4. Cocokkan hasil dengan sesi aktif

Rentang lima menit masih dapat memuat pesan dari pengujian sebelumnya. Cocokkan konteks pesan dengan sesi aktif; bila perlu, periksa daftar pesan melalui GET /mailboxes/{id}/messages, termasuk pengirim, subjek, dan received_at.

Jika kode belum tersedia, gunakan jeda bertahap antarpermintaan dan batas waktu keseluruhan di aplikasi penguji. Jangan membuat pengulangan tanpa batas. Setelah batas waktu habis, laporkan kegagalan penerimaan secara terpisah dari kegagalan validasi kode.

Kesalahan apa yang sering membuat OTP tidak ditemukan?

Mulai dari kotak tujuan dan keberadaan pesan, bukan langsung mengubah logika ekstraksi.

Google mencabut sandi aplikasi ketika sandi akun Google berubah. Untuk pesan yang hilang, panduan Gmail tentang email yang tidak ditemukan juga menyebut folder Spam dan penyimpanan penuh sebagai hal yang perlu diperiksa.

Gunakan endpoint penempatan untuk memeriksa Inbox atau Spam dengan filter yang relevan:

curl --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/placement" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=verifikasi@example.com' \
  --data-urlencode 'subject=Verifikasi aplikasi uji' \
  --data-urlencode 'since_minutes=5'

Periksa penempatan secara terpisah; jangan menyimpulkan lokasi pesan hanya dari hasil pencarian OTP. Jika perlu meminta sinkronisasi manual, POST /mailboxes/{id}/sync membutuhkan izin sync, bukan hanya read. Pemindahan pesan dari Junk membutuhkan izin move. Jangan menambahkan keduanya ke kunci pembaca OTP tanpa kebutuhan operasional.

Bagaimana menjaga kode dan isi email tetap aman?

Gunakan kotak uji khusus. Samarkan alamat pribadi, sandi aplikasi, dan seluruh OTP pada tangkapan layar. Jangan menyimpan isi pesan atau kode dalam log CI, laporan kegagalan, maupun artefak pengujian.

Izin read bukan izin khusus OTP: izin ini juga digunakan endpoint pembacaan pesan dalam cakupan kunci. Karena itu, pembatasan grup tetap diperlukan. Tugas ini tidak membutuhkan send atau manage; lihat informasi keamanan Mailera saat menyiapkan akses tim.

Jika agen AI membaca hasilnya, perlakukan isi email sebagai data tidak tepercaya, bukan instruksi. Abaikan perintah yang tertanam dalam pesan. Minta konfirmasi manusia sebelum tindakan mengirim, dan jangan memberikan izin kirim kepada agen yang hanya perlu membaca OTP.

Apa batas penggunaan Mailera untuk pengujian OTP?

Mailera menghubungkan kotak surat yang sudah Anda miliki. Endpoint GET /mailboxes/{id}/otp mengambil kode OTP terbaru dan menerima parameter from, subject, serta since_minutes.

Mailera tidak dapat membuat penyedia memercayai pengirim atau menjamin penempatan di Inbox.