---
title: "Cara Mengambil Kode OTP Gmail lewat API Mailera"
description: "Ambil OTP dari kotak Gmail uji sendiri lewat API Mailera. Pelajari koneksi sandi aplikasi, izin read, filter pesan, dan cara menghindari kode lama."
url: https://mailera.app/id/blog/cara-ambil-otp-gmail-api-mailera
published: 2026-10-25
updated: 2026-10-25
---

# Cara Mengambil Kode OTP Gmail lewat API Mailera

Hubungkan kotak Gmail uji milik Anda, batasi akses kunci API, lalu ambil kode verifikasi berdasarkan pengirim, subjek, dan rentang waktu.

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

| Bagian | Gmail API langsung | API Mailera |
| --- | --- | --- |
| Jalur akses | REST API Google ke kotak Gmail | REST API Mailera ke kotak yang sudah terhubung |
| Autentikasi | OAuth dengan cakupan akses Google | Sandi aplikasi untuk koneksi Gmail; kunci API untuk pemanggil Mailera |
| Membaca pesan | Aplikasi memakai metode seperti `users.messages.list` dan `users.messages.get` | Aplikasi memakai endpoint pembacaan Mailera |
| Mengambil kode | Aplikasi menyiapkan logika ekstraksi dari isi pesan | Aplikasi memanggil `GET /mailboxes/{id}/otp` |

Menurut dokumentasi [daftar pesan Gmail API](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list), `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](https://developers.google.com/workspace/gmail/api/auth/scopes) sesuai kebutuhan. Untuk jalur Mailera, [halaman pengembang](https://mailera.app/id/developers) menjelaskan akses API, sedangkan [panduan membaca OTP dari kotak sendiri](https://mailera.app/id/blog/ambil-kode-otp-email-api) membahas alur umumnya.

![Alur email verifikasi dari aplikasi uji ke Gmail, sinkronisasi Mailera, dan permintaan kode melalui API.](https://mailera.app/media/06e6aba886bb3737/cara-mengambil-kode-otp-gmail-lewat-api-mailera-alur-otp-id-1200.jpg)
_Pengiriman email dan permintaan OTP adalah dua jalur berbeda; pembaca perlu menunggu pesan tersedia._

## 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](https://mailera.app/id/providers/gmail) memakai sandi aplikasi (app password), bukan sandi masuk akun Google. Google mensyaratkan verifikasi 2 langkah untuk memakai sandi aplikasi. Ikuti [bantuan sandi aplikasi Google](https://support.google.com/accounts/answer/185833?hl=id) dan [panduan verifikasi 2 langkah](https://support.google.com/accounts/answer/185839?hl=id).

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](https://mailera.app/id/blog/sandi-aplikasi-oauth-email-agen-ai) membantu membedakan kredensial koneksi dari akses aplikasi pemanggil.

Pisahkan ketiga rahasia berikut:

| Rahasia | Kegunaan | Tempat penggunaan |
| --- | --- | --- |
| Sandi aplikasi Google | Menghubungkan kotak Gmail | Formulir koneksi Mailera |
| Kunci API Mailera | Mengotorisasi permintaan REST | Header `Authorization` |
| OTP aplikasi uji | Menyelesaikan satu alur verifikasi | Aplikasi penerbit kode |

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.

![Formulir koneksi Gmail Mailera dengan kolom Sandi dan pilihan Grup kotak surat khusus pengujian.](https://mailera.app/media/e1a73d66eb389fda/sandi-aplikasi-atau-oauth-panduan-koneksi-email-untuk-agen-id-1200.jpg)
_Isi kolom Sandi dengan sandi aplikasi Google, bukan sandi masuk akun._

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.

![Pembuatan kunci API Mailera yang dibatasi ke grup uji dan izin baca.](https://mailera.app/media/04cb2cc3e59b48fc/cara-mengambil-kode-otp-gmail-lewat-api-mailera-kunci-api-id-1200.jpg)
_Batasi cakupan ke grup uji; izin read juga memungkinkan pembacaan pesan dalam grup tersebut._

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

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

| Parameter | Fungsi dalam pencarian | Pilihan untuk pengujian |
| --- | --- | --- |
| `from` | Membatasi pengirim | Alamat pengirim aplikasi uji |
| `subject` | Membatasi subjek | Subjek email verifikasi yang dituju |
| `since_minutes` | Membatasi rentang waktu pencarian dalam menit | Rentang pendek yang mencakup pengiriman uji |

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

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

| Gejala | Yang diperiksa | Tindakan |
| --- | --- | --- |
| Pesan yang ditemukan tidak sesuai | `email` dan `id` kotak surat | Pilih ulang `$MAILBOX_ID` berdasarkan alamat uji |
| Pesan terlihat, tetapi pencarian tidak sesuai | Pengirim, subjek, dan rentang waktu | Sesuaikan filter dengan pesan yang benar-benar dikirim |
| Koneksi terputus setelah sandi Google berubah | Sandi aplikasi koneksi | Buat sandi aplikasi pengganti sesuai panduan Google, lalu perbarui koneksi |
| Pesan ada di Gmail tetapi belum terlihat di Mailera | Status dan waktu sinkronisasi | Tunggu pemeriksaan berikutnya atau gunakan sinkronisasi manual dengan izin terpisah |
| Pesan tidak ada di kotak masuk | Folder Spam dan penyimpanan Google | Periksa penempatan pesan serta kapasitas penyimpanan |
| Kode ditemukan tetapi ditolak | Sesi uji dan waktu penerimaan | Ambil pesan yang sesuai sesi aktif, bukan sekadar kode terbaru |

Google mencabut sandi aplikasi ketika sandi akun Google berubah. Untuk pesan yang hilang, [panduan Gmail tentang email yang tidak ditemukan](https://support.google.com/mail/answer/7015314?hl=id) juga menyebut folder Spam dan penyimpanan penuh sebagai hal yang perlu diperiksa.

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

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

**Lakukan ini dengan API** — Setiap tindakan dalam artikel ini tersedia melalui REST API, lengkap dengan contoh curl, API key, dan webhook. [Lihat dokumentasi API](https://mailera.app/id/docs)