---
title: "Cara Mengambil Kode OTP Email lewat API dari Kotak Surat Sendiri"
description: "Panduan mengambil OTP email lewat API Mailera dari kotak surat uji sendiri, dengan filter pengirim, pemeriksaan waktu, dan diagnosis pesan di Junk."
url: https://mailera.app/id/blog/ambil-kode-otp-email-api
published: 2026-10-25
updated: 2026-10-25
---

# Cara Mengambil Kode OTP Email lewat API dari Kotak Surat Sendiri

Hubungkan kotak surat uji, ambil kode dengan izin read, lalu pastikan pesan itu berasal dari percobaan yang sedang berjalan. Contoh ini berfokus pada membaca email yang sudah diterima, bukan mengirim OTP.

## Ringkasan: bagaimana mengambil OTP dari email sendiri?

Untuk mengambil OTP dari email sendiri, hubungkan kotak surat uji ke Mailera, buat kunci API berizin `read`, lalu panggil `GET /mailboxes/{id}/otp` dengan filter pengirim dan subjek. Mailera membaca email yang diterima, bukan membuat alamat baru. Cocokkan pesan dengan percobaan pengujian Anda sebelum memakai kodenya: berhasil mengambil OTP tidak berarti kode itu masih berlaku atau akan diterima aplikasi.

OTP email adalah kode sekali pakai yang dikirim melalui email untuk langkah verifikasi. Dalam panduan ini, kode berasal dari aplikasi yang Anda uji dan masuk ke kotak surat uji milik Anda sendiri. Jangan mengasumsikan semua OTP memiliki panjang, format, atau masa berlaku yang sama.

## Apa bedanya API pengiriman OTP dan API pembacaan OTP?

API pengiriman memulai pengiriman pesan berisi kode. API pembacaan mengambil informasi dari pesan yang telah diterima. Jika tujuan Anda menguji formulir verifikasi tanpa menyalin kode secara manual, bagian yang dibutuhkan adalah pembacaan, disertai pemeriksaan bahwa pesan tersebut cocok dengan percobaan aktif.

| Tugas | Komponen yang bertanggung jawab | Masukan | Hasil yang diharapkan |
| --- | --- | --- | --- |
| Meminta OTP | Aplikasi yang diuji | Permintaan verifikasi akun uji | Aplikasi memulai pengiriman email |
| Menerima email | Penyedia kotak surat | Email dari aplikasi | Pesan tersedia di kotak surat uji |
| Mengambil kode | Mailera dan program pengujian | ID kotak surat serta filter pencarian | Kode dari email yang cocok |
| Memeriksa kode | Aplikasi yang diuji | Kode dari percobaan yang sesuai | Aplikasi menerima atau menolak verifikasi |

[Mailera menghubungkan kotak surat yang sudah Anda miliki](https://mailera.app/id/product) ke aplikasi melalui REST API, MCP, dan webhook. Dalam alur ini, Mailera membantu membaca pesan; keputusan menerima kode tetap berada pada aplikasi yang diuji.

![Alur aplikasi uji mengirim email, Mailera membaca kotak surat, dan program pengujian meneruskan kode ke aplikasi.](https://mailera.app/media/a195f75a6f27753b/cara-mengambil-kode-otp-email-lewat-api-dari-kotak-surat-id-1200.jpg)
_Membaca kode dan memvalidasi kode adalah dua tahap yang berbeda._

Pisahkan hasil kedua tahap itu dalam pengujian. “Kode berhasil dibaca” adalah hasil pembacaan email. “Verifikasi berhasil” baru tercapai setelah aplikasi menerima kode tersebut. Pemisahan ini membantu Anda menentukan apakah kegagalan terjadi pada pencarian pesan atau pada alur verifikasi aplikasi.

## Apa yang perlu disiapkan sebelum mengambil kode?

Siapkan kotak surat uji khusus, akses ke aplikasi yang dapat memicu email verifikasi, dan akses Mailera untuk menghubungkan kotak surat tersebut. Hanya peran Admin atau Leader yang dapat menambahkan kotak surat. Jika peran Anda tidak memiliki akses itu, minta anggota tim dengan peran yang sesuai menyiapkan koneksinya.

Untuk Outlook atau Microsoft 365, gunakan OAuth melalui **Masuk dengan Microsoft**. Mailera tidak menggunakan sandi aplikasi untuk koneksi Microsoft. Rincian koneksi ada di [panduan penyedia Microsoft](https://mailera.app/id/providers/microsoft); jika koneksi lama Anda mengandalkan sandi aplikasi, baca [mengganti sandi aplikasi Outlook yang gagal dengan OAuth](https://mailera.app/id/blog/kata-sandi-aplikasi-outlook-gagal-oauth).

Pendekatan ini sejalan dengan autentikasi Microsoft Graph yang menggunakan access token dari Microsoft identity platform. Microsoft juga menyarankan [izin Graph minimum yang diperlukan aplikasi](https://learn.microsoft.com/en-us/graph/auth/auth-concepts). Jangan menyamakan izin akses penyedia tersebut dengan scope kunci API Mailera: untuk pembacaan OTP melalui Mailera, scope yang diperlukan adalah `read`.

Koneksi Gmail di Mailera menggunakan sandi aplikasi (app password). Menurut [dokumentasi sandi aplikasi Google](https://support.google.com/accounts/answer/185833), akun harus mengaktifkan verifikasi 2 langkah. Google merekomendasikan “Sign in with Google” ketika pilihan itu tersedia, dan mencabut sandi aplikasi saat sandi akun Google berubah. Gunakan [panduan koneksi Gmail di Mailera](https://mailera.app/id/providers/gmail) untuk pengaturan yang sesuai dengan jalur koneksi ini.

Untuk iCloud, koneksi Mailera juga menggunakan sandi aplikasi. [Dokumentasi sandi khusus aplikasi Apple](https://support.apple.com/en-us/102654) mensyaratkan autentikasi dua faktor pada Apple Account. Jika Anda sedang memilih metode koneksi untuk beberapa penyedia, baca [panduan sandi aplikasi dan OAuth untuk kotak surat agen](https://mailera.app/id/blog/sandi-aplikasi-oauth-email-agen-ai) sebelum menyiapkan kredensial.

## Bagaimana mengambil OTP melalui REST API Mailera?

Lakukan penyiapan koneksi dan kunci lebih dahulu. Setelah keduanya siap, mulailah percobaan verifikasi baru agar waktu pencarian tidak tercampur dengan pekerjaan penyiapan.

### 1. Hubungkan kotak surat uji

Buka **Kotak surat → Tambah kotak surat**. Untuk Microsoft, pilih **Masuk dengan Microsoft**. Untuk penyedia dengan sandi aplikasi, pilih **Satu kotak surat**, isi **Alamat email**, lalu pilih **Lanjutkan** dan lengkapi **Detail koneksi**.

Tombol **Uji & hubungkan** menguji koneksi tanpa mengirim email. Periksa hasil **Login ke server masuk** dan **Deteksi folder**. Jika koneksi pengiriman gagal tetapi penerimaan berhasil, Anda dapat memilih **Simpan khusus penerimaan**. Pengujian pembacaan OTP tidak memerlukan Mailera untuk mengirim pesan.

Setelah tersambung, periksa status kotak surat. Endpoint `GET /mailboxes/{id}/status` memeriksa login Microsoft secara langsung; untuk penyedia lain, statusnya berdasarkan sinkronisasi terakhir. Karena itu, perhatikan juga waktu sinkronisasi saat menelusuri masalah koneksi.

### 2. Buat kunci dengan izin minimum

Di **Pengaturan**, buka bagian kunci API dan pilih **Buat API key**. Isi **Nama deskriptif**, pilih grup uji pada **Cakupan kotak surat**, aktifkan izin `read`, lalu atur **Masa berlaku** sesuai kebutuhan pekerjaan pengujian.

Kunci hanya ditampilkan sekali. Simpan sebagai rahasia di sisi server dan sediakan nilainya melalui variabel lingkungan `$MAILERA_API_KEY`. Jangan menempelkan nilainya langsung ke skrip, repositori, atau konfigurasi yang dapat dibaca peramban.

![Pengaturan kunci API Mailera dengan cakupan grup kotak surat uji dan izin pembacaan.](https://mailera.app/media/49c4717077900701/cara-mengambil-kode-otp-email-lewat-api-dari-kotak-surat-id-1200.jpg)
_Batasi kunci pembaca OTP ke grup uji dan izin read._

Periksa cakupan grup dan izin kunci, bukan hanya apakah kunci sudah dibuat. Kunci untuk grup yang salah tidak membantu program membaca kotak surat uji yang Anda maksud.

### 3. Pilih ID kotak surat yang benar

Jalankan permintaan berikut di lingkungan lokal yang aman, bukan pada langkah CI yang merekam seluruh keluaran:

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

Respons memuat daftar kotak surat pada `data`. Cocokkan `email` dengan kotak surat uji Anda, lalu simpan `id` kotak surat tersebut sebagai `$MAILBOX_ID`. Jangan otomatis memakai elemen pertama hanya karena permintaan berhasil.

Anda juga dapat memeriksa `status` dan `last_sync_at`. Jika daftar memiliki lebih banyak hasil daripada yang ditampilkan, endpoint ini menyediakan parameter `limit` dan `offset`. Rincian integrasi tersedia di [halaman pengembang Mailera](https://mailera.app/id/developers).

### 4. Catat awal percobaan, lalu minta OTP

Catat waktu mulai percobaan di program pengujian sebelum meminta aplikasi mengirim OTP. Simpan juga identitas akun uji dan, jika aplikasi Anda mendukungnya, penanda unik percobaan.

Gunakan satu permintaan verifikasi yang jelas sebagai titik awal. Jangan langsung meminta kode berulang kali hanya karena email belum terlihat; beberapa permintaan akan membuat Anda harus membedakan pesan untuk percobaan yang berbeda.

### 5. Panggil endpoint OTP dengan filter

`GET /mailboxes/{id}/otp` mengambil kode OTP terbaru dan memerlukan scope `read`. Endpoint ini menerima parameter berikut:

| Parameter | Penggunaan | Nilai yang dikirim |
| --- | --- | --- |
| `id` pada path | Menentukan kotak surat | Gunakan ID kotak surat uji yang sudah dicocokkan |
| `from` | Menyaring pengirim | Gunakan pengirim email verifikasi aplikasi uji |
| `subject` | Menyaring subjek | Gunakan subjek email verifikasi yang diharapkan |
| `since_minutes` | Parameter yang diterima endpoint OTP | Contoh di bawah menggunakan `5` |

Contoh berikut menyertakan `since_minutes=5`. Ganti pengirim dan subjek dengan nilai dari aplikasi uji Anda. Alamat `verifikasi@example.com` hanya contoh. Untuk memeriksa waktu pesan, bandingkan `received_at` dari hasil pencarian pada langkah berikutnya dengan waktu mulai percobaan yang dicatat program.

```bash
OTP_RESPONSE=$(curl --silent --show-error --fail --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=Kode verifikasi aplikasi uji" \
  --data-urlencode "since_minutes=5")
```

Penugasan tersebut menyimpan respons ke variabel shell, bukan mencetaknya. Nonaktifkan pelacakan perintah shell dan jangan menjalankan `echo "$OTP_RESPONSE"` pada log CI. Gunakan [referensi REST API Mailera](https://mailera.app/id/docs) saat menulis pembacaan respons endpoint ini di program Anda.

### 6. Periksa pesan sumber sebelum meneruskan kode

Jika pengujian memerlukan metadata pesan bersama hasil ekstraksi, endpoint pencarian menyediakan parameter `extract=otp`. Contoh berikut menyimpan respons tanpa mencetaknya:

```bash
SEARCH_RESPONSE=$(curl --silent --show-error --fail --get \
  "https://mailera.app/api/public/v1/messages/search" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode "mailbox=$MAILBOX_ID" \
  --data-urlencode "from=verifikasi@example.com" \
  --data-urlencode "q=code" \
  --data-urlencode "extract=otp")
```

Sesuaikan `q` dengan isi email uji Anda. Pada hasil pencarian dengan ekstraksi OTP, setiap pesan di `data` dapat Anda periksa melalui `id`, `mailbox_id`, `from.address`, `subject`, dan `received_at`; kode hasil ekstraksi berada pada `otp.code`.

Di program pengujian, pilih pesan berdasarkan metadata dan konteks percobaannya terlebih dahulu, baru baca `otp.code`. Jangan memperlakukan `data[0]` sebagai jawaban tanpa pemeriksaan. Jika perlu membaca isi lengkap, gunakan `GET /mailboxes/{id}/messages/{msgId}` dengan ID pesan yang dipilih; responsnya menyediakan `body.text` dan `body.html`.

Teruskan kode ke langkah verifikasi aplikasi tanpa mencetaknya. Untuk hasil pengujian, cukup catat apakah pesan yang sesuai ditemukan dan apakah aplikasi menerima kode.

## Bagaimana menghindari OTP lama atau kode dari percobaan lain?

Kode terbaru dalam pencarian belum tentu berasal dari percobaan yang sedang berjalan. Misalnya, Anda memulai percobaan baru ketika email dari percobaan sebelumnya belum diterima. Waktu penerimaan yang baru tidak dengan sendirinya menghubungkan email itu dengan permintaan baru.

Cocokkan kotak surat, pengirim, dan subjek yang diharapkan. Bandingkan `received_at` pada hasil pencarian pesan dengan waktu mulai percobaan yang dicatat program. Pemeriksaan waktu membantu menolak pesan lama, tetapi Anda tetap perlu mencocokkan konteks pesan dengan percobaan yang sedang berjalan.

Jika aplikasi uji Anda dapat menyertakan penanda unik percobaan di subjek atau isi email, cocokkan penanda itu sebelum memakai kode. Penanda tersebut merupakan rancangan aplikasi uji Anda, bukan fitur korelasi otomatis Mailera. Untuk pengujian paralel, pilih rancangan yang memungkinkan setiap proses mengenali pesannya sendiri; jangan mengandalkan urutan kedatangan bersama.

![Urutan pemeriksaan waktu dan kecocokan percobaan untuk menghindari penggunaan OTP lama.](https://mailera.app/media/970a9da08efb3611/cara-mengambil-kode-otp-email-lewat-api-dari-kotak-surat-id-1200.jpg)
_Bandingkan received\_at dengan waktu mulai percobaan; kecocokan konteks dan validitas kode tetap perlu diperiksa._

Kecocokan waktu dan konteks pesan tidak memastikan kode masih berlaku. Aplikasi tujuan tetap harus memeriksa validitas kode dalam alur verifikasinya.

Untuk menunggu email, gunakan pemeriksaan berkala dengan batas waktu keseluruhan dan jeda yang meningkat. Hentikan penantian ketika pesan yang cocok ditemukan atau batas waktu tercapai. Jangan membuat pengulangan tanpa batas, dan jangan memicu pengiriman OTP baru pada setiap pemeriksaan.

Jika batas waktu tercapai, tandai percobaan gagal dan simpan informasi diagnosis yang tidak sensitif. Mulai percobaan berikutnya dengan identitas baru atau pemisahan yang jelas, agar email terlambat dari percobaan sebelumnya tidak dianggap sebagai hasil baru.

## Kesalahan umum: mengapa OTP belum ditemukan?

Periksa jalur penerimaan pesan sebelum mengubah cara mengambil kode. Bedakan pesan yang belum terlihat, koneksi yang bermasalah, dan pesan yang ada tetapi tidak cocok dengan filter Anda.

| Gejala | Hal yang perlu diperiksa | Tindakan berikutnya |
| --- | --- | --- |
| Kotak surat yang dicari tidak muncul | Cakupan grup kunci dan ID kotak surat | Cocokkan kembali hasil `GET /mailboxes` |
| Kotak surat tidak menerima pesan baru | Status koneksi dan waktu sinkronisasi terakhir | Periksa endpoint status dan perbaiki koneksi bila diperlukan |
| Pesan terlihat, tetapi pencarian tidak cocok | Pengirim, subjek, dan kata pencarian | Bandingkan filter dengan metadata pesan sebenarnya |
| Email tidak terlihat di Inbox | Penempatan pesan di Junk | Periksa endpoint placement dan folder Junk |
| Sinkronisasi manual ditolak | Izin kunci API | Gunakan kunci dengan scope `sync` untuk operasi sinkronisasi |
| Kode ditemukan, tetapi ditolak aplikasi | Kecocokan percobaan dan validitas kode | Periksa pesan sumber serta alur verifikasi aplikasi |

Untuk membedakan Inbox dan Spam, gunakan `GET /mailboxes/{id}/placement`. Endpoint ini menerima parameter `from`, `subject`, dan `since_minutes`. Anda juga dapat melihat folder Junk melalui antarmuka Mailera atau membaca daftar pesan dengan `GET /mailboxes/{id}/messages` dan parameter `folder=junk`.

Penerimaan email dan sinkronisasi dapat tertunda. `POST /mailboxes/{id}/sync` meminta sinkronisasi segera dan dapat membangunkan kotak surat yang sedang tidur, tetapi operasi ini memerlukan scope `sync`, terpisah dari `read`. Jangan menambahkan izin itu ke semua kunci pembaca hanya untuk berjaga-jaga.

Jika Anda perlu memindahkan pesan dari Junk, gunakan **Bukan spam** atau operasi pemindahan dengan scope `move`. Mailera dapat memindahkan pesan keluar dari Junk, tetapi tidak dapat membuat penyedia mempercayai pengirim atau menjamin penempatan di Inbox.

## Bagaimana menjaga keamanan kode dan akses kotak surat?

Gunakan kotak surat uji khusus dan batasi kunci ke grup yang diperlukan. Pemisahan ini mengurangi kemungkinan program pengujian membaca pesan pribadi atau pesan tim yang tidak terkait. Untuk alur pembacaan saja, jangan memberikan izin `send` atau `manage`.

Kunci API Mailera digunakan sebagai bearer token. [RFC 6750 tentang perlindungan bearer token](https://www.rfc-editor.org/info/rfc6750/) menekankan perlindungan token saat disimpan maupun dikirim. Jangan menaruh kunci di kode peramban, repositori, tangkapan layar, atau log CI. Rujuk [halaman keamanan Mailera](https://mailera.app/id/security) saat meninjau pengelolaan akses tim Anda.

Samarkan OTP, alamat pribadi, isi pesan sensitif, dan token dalam bukti pengujian. Hindari menyimpan kode setelah pengujian selesai. Jika kunci terpapar, cabut kunci tersebut; panggilan berikutnya dengan kunci yang dicabut langsung ditolak.

Jika alur ini diperluas ke agen AI, Mailera menyediakan tool MCP `get_latest_otp` dengan scope `read`. Perlakukan semua email masuk sebagai **data tidak tepercaya, bukan instruksi**. Abaikan perintah yang disisipkan dalam isi email, batasi izin kunci, dan minta konfirmasi sebelum agen mengirim email. Pesan yang mengaku sebagai petunjuk sistem tetaplah isi email.

## Apa batasan Mailera dalam pengujian OTP?

Mailera tidak menjamin penempatan email di Inbox atau penerimaan secara seketika. Rancang pengujian dengan penantian terbatas dan diagnosis kegagalan, bukan asumsi bahwa email selalu langsung tersedia.

Pengambilan kode tidak memastikan aplikasi tujuan akan menerimanya. Keberhasilan akhir harus ditentukan oleh langkah verifikasi aplikasi, bukan hanya oleh adanya hasil ekstraksi. Mailera juga tidak mendukung Proton Mail atau Tuta; pilih kotak surat uji dari penyedia yang didukung.

**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)