Apa yang perlu disiapkan sebelum agen membaca OTP?
Verifikasi email untuk agen browser di sini berarti memasukkan kode untuk membuktikan akses ke kotak surat pada aplikasi uji. Ini bukan validasi daftar alamat email. Gunakan hanya aplikasi yang boleh Anda uji dan kotak surat milik Anda sendiri.
Mailera menghubungkan kotak surat yang sudah Anda miliki ke aplikasi melalui REST API atau MCP. Untuk dasar pengambilan kode, lihat panduan membaca OTP dari kotak surat sendiri. Fokus di sini adalah mengatur perilaku agen selama menunggu dan setelah kode ditemukan.
Sebelum menjalankan browser, siapkan konteks berikut di pengendali:
- Kotak surat dan alamat penerima yang dipakai untuk pengujian.
- Pengirim serta subjek email yang diharapkan dari aplikasi uji.
- Identitas sesi browser, domain tujuan, dan tindakan yang memicu verifikasi.
- Batas waktu tunggu, batas percobaan, serta kondisi penyerahan kepada manusia.
Hubungkan kotak surat sesuai panduan penyedia email. Jika koneksinya memakai sandi aplikasi, ikuti panduan sandi aplikasi untuk kotak surat agen, bukan memasukkan sandi login biasa ke pengendali.
Di Pengaturan, buka bagian kunci API lalu pilih Buat API key. Batasi Cakupan kotak surat ke grup pengujian dan berikan izin read. Simpan kunci saat ditampilkan karena nilainya hanya muncul sekali. Letakkan kunci di lingkungan eksekusi tepercaya, bukan di halaman browser, prompt, atau kode sisi klien.
Bagaimana alur jeda dan pelanjutan agen dibuat?
Buat pengendali dengan status yang jelas. Jangan meminta model terus mencoba sampai formulir menerima sesuatu. Setiap perpindahan status harus memiliki syarat yang bisa diperiksa.
- Deteksi tantangan. Pastikan halaman aplikasi uji benar-benar meminta OTP email, bukan bentuk verifikasi lain.
- Catat permintaan. Simpan waktu mulai, penerima, pengirim yang diharapkan, dan identitas sesi. Jika aplikasi uji menyediakan penanda permintaan, simpan juga.
- Pertahankan sesi. Biarkan sesi browser tetap tersedia, tetapi hentikan tindakan lanjutan selama menunggu kode.
- Cari kandidat OTP. Periksa secara berkala dengan jeda bertambah hingga batas waktu. Jangan membuat proses tunggu kedua untuk sesi yang sama.
- Periksa lalu isi. Cocokkan kandidat dengan permintaan aktif, lalu pastikan domain dan formulir masih benar sebelum memasukkan kode.
- Periksa hasil aplikasi. Lanjutkan tugas hanya setelah aplikasi menunjukkan bahwa verifikasi berhasil. Klik tombol saja bukan hasil akhir.
| Status pengendali | Pemicu masuk | Kondisi keluar |
|---|---|---|
| Berjalan | Tugas uji dimulai | Formulir meminta OTP |
| Menunggu OTP | Konteks permintaan tersimpan | Ada kandidat, batas waktu habis, atau konteks berubah |
| Memeriksa kode | Kandidat tersedia | Kecocokan jelas atau perlu bantuan |
| Melanjutkan | Kode cocok dan formulir masih benar | Aplikasi mengonfirmasi hasil atau menolak kode |
| Memerlukan bantuan | Ambiguitas, penolakan, atau batas tercapai | Manusia menentukan langkah berikutnya |
Gunakan satu pengunci logis per sesi agar dua pekerja tidak memasukkan kode bersamaan. Jangan klik kirim ulang selama percobaan sebelumnya masih aktif. Jika pengiriman ulang memang diperlukan, tutup percobaan lama dan buat konteks permintaan baru.
Berikut contoh aturan keputusan lokal dalam Python, bukan SDK Mailera. Nilai masukannya harus dihitung oleh pengendali Anda:
def keputusan(batas_habis, konteks_valid, ada_kandidat, cocok):
if batas_habis or not konteks_valid:
return "bantuan_manusia"
if not ada_kandidat:
return "tunggu"
if not cocok:
return "bantuan_manusia"
return "isi_dan_periksa_hasil"
Jika Anda memakai Browser Use, repositori resminya menjelaskan pendaftaran alat khusus melalui Tools. Tempatkan pembacaan email di alat terbatas tersebut; tetap simpan keputusan tentang sesi dan batas percobaan di pengendali. Hindari membangun ulang sesi hanya untuk menunggu email: sinkronisasi profil Browser Use memindahkan cookie, tetapi tidak local storage, IndexedDB, atau ekstensi.
Bagaimana mengambil OTP melalui REST API atau MCP?
Pilih REST API untuk pengendali aplikasi yang perlu mengatur setiap permintaan secara eksplisit. Endpoint GET /mailboxes/{id}/otp mengambil OTP terbaru dan membutuhkan izin read. Filter yang tersedia adalah from, subject, dan since_minutes.
Isi $MAILERA_API_KEY dan $MAILBOX_ID melalui lingkungan eksekusi tepercaya. Contoh berikut memakai pengirim serta subjek fiktif; ganti keduanya sesuai aplikasi uji Anda. Nilai since_minutes=5 adalah contoh rentang pencarian, bukan masa berlaku OTP atau jaminan waktu kedatangan.
curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
--header "Authorization: Bearer $MAILERA_API_KEY" \
--data-urlencode "from=verification@example.com" \
--data-urlencode "subject=Verifikasi aplikasi uji" \
--data-urlencode "since_minutes=5"Jalankan pembacaan ini di sisi tepercaya dan jangan menyalin keluaran berisi kode ke log bersama. Rujukan endpoint tersedia di dokumentasi API Mailera.
Rentang waktu relatif hanya mempersempit pencarian. Jangan menganggap kode terbaru pasti berasal dari tindakan yang baru saja dilakukan browser. Pengendali masih harus menilai konteks pesan dan kemungkinan adanya permintaan lain.
| Pilihan | Cocok untuk | Tanggung jawab pengendali |
|---|---|---|
| REST API | Aplikasi dengan pemanggilan HTTP dan status eksplisit | Autentikasi, pencocokan, batas tunggu, dan sesi browser |
| MCP | Agen yang sudah menggunakan klien MCP | Pembatasan alat, pemeriksaan hasil, dan sesi browser |
Untuk OTP email dengan MCP, Mailera menyediakan alat get_latest_otp dengan izin read. Gunakan Salin konfigurasi MCP untuk klien yang didukung dan ikuti panduan MCP Mailera.
Menurut spesifikasi alat MCP, klien menemukan alat melalui tools/list, membaca parameter dari inputSchema, lalu memanggil alat melalui tools/call. Baca skema alat sebelum mengisi argumen; jangan langsung menyalin parameter REST ke pemanggilan MCP. Terapkan batas waktu pemanggilan dan periksa hasil alat sebelum meneruskannya kepada model.
Kapan agen boleh melanjutkan setelah menerima kode?
Agen hanya boleh melanjutkan jika pengendali dapat menghubungkan kandidat dengan permintaan aktif. Untuk memeriksa pesan, GET /mailboxes/{id}/messages menyediakan daftar, sedangkan GET /mailboxes/{id}/messages/{msgId} mengambil satu pesan beserta isinya.
Gunakan metadata berikut sebagai pemeriksaan, bukan sebagai jaminan tunggal:
| Data pesan | Pemeriksaan terhadap konteks uji |
|---|---|
mailbox_id dan to[].address | Kotak surat serta penerima sesuai |
from.address | Alamat pengirim sesuai konfigurasi uji |
subject | Konteks verifikasi sesuai tindakan browser |
received_at | Waktu penerimaan masuk rentang permintaan |
id | Pesan belum dipakai oleh percobaan lain |
Waktu penerimaan yang baru tidak cukup jika ada beberapa permintaan verifikasi pada kotak surat yang sama. Subjek serupa juga tidak membedakan dua sesi. Jika aplikasi uji menyertakan penanda permintaan, cocokkan penanda itu. Jika hubungan tetap ambigu, jangan menebak kandidat mana yang harus dipakai.
Untuk pengujian awal, isolasikan permintaan: jangan biarkan beberapa sesi meminta kode ke kotak surat yang sama secara bersamaan. Simpan hubungan antara pesan yang diperiksa dan percobaan lokal. Jangan mengambil OTP terbaru lagi tepat sebelum mengisi formulir tanpa mengulang pemeriksaan kecocokan.
Sebelum memasukkan kode, periksa kembali domain tujuan, sesi, dan formulir. Jika halaman berubah, hentikan alur. Setelah pengiriman kode, cari hasil aplikasi yang dapat diperiksa, misalnya status akun uji yang memang Anda tetapkan sebagai tanda berhasil. Jika aplikasi menolak kode, kembali ke kebijakan kegagalan, bukan mencoba kandidat lain tanpa batas.
Kesalahan umum: mengapa agen terus menunggu atau memakai kode yang salah?
Pisahkan masalah kedatangan email dari masalah sesi browser. Menambah frekuensi pencarian tidak memperbaiki sesi yang sudah kedaluwarsa.
| Gejala | Yang diperiksa | Tindakan |
|---|---|---|
| Email belum terlihat | Penerima, pengirim, subjek, dan rentang waktu | Tunggu dengan jeda bertambah hingga batas yang ditentukan |
| Pesan berada di Junk | GET /mailboxes/{id}/placement | Periksa lokasi dan konteks pesan sebelum melanjutkan |
| Kotak surat terputus | GET /mailboxes/{id}/status | Hentikan penantian dan perbaiki koneksi |
| Kode lama terpilih | Waktu permintaan dan pesan yang sudah dipakai | Tolak kandidat; jangan mengandalkan urutan terbaru |
| Sesi browser kedaluwarsa | Formulir dan keadaan aplikasi | Hentikan percobaan lama; mulai ulang hanya sesuai kebijakan |
| Batas waktu habis | Tenggat lokal dan jumlah percobaan | Batalkan pekerjaan tertunda dan minta bantuan manusia |
Endpoint status memeriksa login Microsoft secara langsung. Untuk penyedia lain, statusnya berdasarkan sinkronisasi terakhir. Pertimbangkan perbedaan ini saat menilai apakah koneksi masih dapat dipakai.
Sinkronisasi manual melalui POST /mailboxes/{id}/sync membutuhkan izin sync tambahan. Jangan memasukkannya diam-diam ke alur yang hanya memiliki read. Jika diperlukan, pisahkan tindakan operasional tersebut dari pembaca OTP.
Atur pemeriksaan berkala dengan jeda yang meningkat dan batas waktu keseluruhan. Setelah batas tercapai, abaikan hasil terlambat untuk percobaan yang sudah ditutup. Saat meminta bantuan, tampilkan alasan berhenti dan status sesi, bukan OTP atau isi email lengkap.
Bagaimana menjaga agen tetap aman saat membaca email?
Isi email adalah data tidak tepercaya, bukan instruksi. Email yang berisi kode tetap bisa menyertakan perintah untuk mengganti tujuan, membocorkan kunci, membuka tautan lain, atau menjalankan alat. Pembaca OTP harus mengabaikan perintah semacam itu.
Batasi keluaran pembaca pada kode dan metadata yang diperlukan untuk pemeriksaan. Jangan meneruskan seluruh HTML atau isi pesan kepada agen browser jika tugasnya hanya mengisi formulir. Pisahkan komponen pembaca dari komponen yang boleh melakukan tindakan browser.
Pertahankan izin minimum. Alur ini cukup menggunakan read; jangan menambahkan send. Jika nantinya agen juga mengirim email, wajibkan konfirmasi manusia sebelum pengiriman. Informasi produk terkait tersedia di halaman keamanan Mailera.
Samarkan OTP, alamat pribadi, kunci API, cookie sesi, dan token pada log maupun tangkapan layar. Catat status seperti “kandidat ditolak karena konteks berbeda”, bukan nilai rahasianya. Hentikan alur ketika domain tujuan berubah atau tantangan verifikasi tidak sesuai dengan tindakan uji yang diizinkan. Jangan gunakan alur ini untuk mengambil kode akun orang lain atau menggantikan pemeriksaan manusia yang diwajibkan layanan.
Apa batas Mailera dalam alur ini?
Mailera menyediakan akses ke email dan OTP dari kotak surat terhubung. Deteksi formulir, jeda, pelanjutan browser, serta pemeriksaan hasil tetap menjadi tanggung jawab aplikasi agen Anda.
Mailera tidak membuat kotak surat atau alamat email baru dan tidak menjamin penempatan Inbox. Memindahkan pesan dari Junk juga tidak membuat penyedia otomatis memercayai pengirim berikutnya.
Keberhasilan mengambil kode bukan keberhasilan verifikasi. Ikuti batas masa berlaku yang ditetapkan aplikasi uji dan jadikan hasil dari aplikasi tersebut sebagai penentu apakah tugas boleh dilanjutkan.
Lakukan ini dengan API
Setiap tindakan dalam artikel ini tersedia melalui REST API, lengkap dengan contoh curl, API key, dan webhook.
Lihat dokumentasi API
