ดึง OTP จาก Outlook ผ่าน API ให้ตรงกับรอบทดสอบ

ต้องเตรียมอะไร และควรใช้ Microsoft Graph หรือ Mailera?

งานนี้คือการอ่านรหัสยืนยันจากอีเมล Outlook เพื่อทดสอบการเข้าสู่ระบบ ใช้เฉพาะกล่องจดหมายของคุณและระบบที่คุณมีสิทธิ์ทดสอบ ไม่ใช่การส่ง OTP ทาง SMS หรือการกู้คืนบัญชี Microsoft

ถ้าต้องการอ่านรหัสโดยไม่เขียนส่วนแยกรหัสเอง ให้ใช้ปลายทาง OTP ของ Mailera แต่ถ้าต้องการควบคุมการอ่านข้อความและกติกาแยกรหัสเอง ก็เรียก Microsoft Graph โดยตรงได้ งานที่คุณต้องรับผิดชอบต่างกันดังนี้

เอกสาร Microsoft แยกการอ่านรายการข้อความด้วย Graph ออกจากการอ่านรายละเอียดข้อความ ส่วน Mailera เชื่อมกล่องจดหมายที่มีอยู่แล้วให้เรียกผ่าน API ได้

แยกข้อมูลรับรองสองชุดให้ชัด: OAuth ใช้อนุญาตให้เข้าถึงบัญชี Microsoft ส่วนคีย์ API ใช้ยืนยันตัวตนเมื่อเรียก Mailera ห้ามนำ Microsoft access token มาใส่แทน $MAILERA_API_KEY เอกสารการขอสิทธิ์เข้าถึง Graph ในนามผู้ใช้ อธิบายขั้นตอนรับ token และขอความยินยอมของ Microsoft

สำหรับ Microsoft 365 ของบริษัท ให้ตรวจการอนุญาตกับผู้ดูแลระบบก่อนนำเข้าชุดทดสอบ เอกสาร OAuth authorization code flow ระบุว่าสิทธิ์บางประเภทจำกัดให้ผู้ดูแลระบบอนุมัติ หากหน้าขอความยินยอมไม่อนุญาตให้ดำเนินการต่อ ให้แก้เรื่องสิทธิ์ก่อนแก้โค้ดอ่าน OTP

พื้นฐานที่ใช้ร่วมกันระหว่างผู้ให้บริการอยู่ในคู่มืออ่าน OTP จากกล่องจดหมายของคุณ ส่วนขั้นตอนต่อไปนี้ใช้กับ Outlook และ Microsoft 365 โดยเฉพาะ

เชื่อม Outlook และสร้างคีย์อ่านอีเมลอย่างไร?

1. เชื่อมบัญชีด้วย OAuth ให้ผู้มีบทบาท Admin หรือ Leader เปิด กล่องจดหมาย → เพิ่มกล่องจดหมาย แล้วเลือก ลงชื่อเข้าใช้ด้วย Microsoft จากนั้นลงชื่อเข้าใช้บัญชีทดสอบและอนุญาตการเข้าถึงที่ Microsoft แสดง Mailera เชื่อมบัญชี Microsoft ผ่าน Graph ไม่ใช้รหัสผ่านสำหรับแอป (app password) ดูรายละเอียดได้ที่หน้าเชื่อม Outlook และ Microsoft 365 หากคุณดูแลกล่องจากผู้ให้บริการอื่นด้วย ให้แยกวิธีเชื่อมต่อออกจากกันตามคู่มือรหัสผ่านสำหรับแอปของกล่องจดหมายที่ใช้กับ agent
2. สร้างคีย์สำหรับชุดทดสอบ เปิด การตั้งค่า ไปที่แท็บ API key แล้วเลือก สร้าง API key ตั้ง ชื่อที่สื่อความหมาย เลือกกลุ่มทดสอบใน ขอบเขตกล่องจดหมาย และเลือกสิทธิ์อ่าน read กำหนด ระยะเวลาที่ใช้ได้ ให้เหมาะกับงาน ไม่ต้องเพิ่ม send หรือ manage
3. เก็บคีย์แล้วระบุกล่องให้ถูกต้อง เมื่อเห็น สร้าง API key แล้ว — คัดลอกตอนนี้ ให้เก็บคีย์ในระบบจัดการความลับของชุดทดสอบ คีย์แสดงเพียงครั้งเดียว ตั้งตัวแปรสภาพแวดล้อม $MAILERA_API_KEY แล้วเรียกรายการกล่องจดหมาย

curl --get 'https://mailera.app/api/public/v1/mailboxes' \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'provider=microsoft'

ตรวจ email ของรายการใน data ว่าเป็นกล่องทดสอบที่ต้องการ แล้วนำ id ของรายการนั้นไปตั้งเป็น $MAILBOX_ID อย่าเลือกจากตำแหน่งแรกของผลลัพธ์อย่างเดียว

ผลลัพธ์ยังมี provider, status และ last_sync_at ให้ใช้ประกอบการตรวจกล่อง หากต้องสั่งซิงก์ระหว่างวิเคราะห์ปัญหา ให้แยกคีย์สิทธิ์ sync ออกจากคีย์อ่านที่ชุดทดสอบใช้งานประจำ

เรียก API เพื่ออ่านรหัสของรอบทดสอบนี้อย่างไร?

4. เริ่มรอบทดสอบก่อนขอรหัส บันทึกเวลาเริ่มรอบไว้ในชุดทดสอบ แล้วกระตุ้นให้ระบบของคุณส่งอีเมลยืนยันเข้ากล่อง Outlook ที่เลือก หากควบคุมแม่แบบอีเมลทดสอบได้ ให้ใส่ตัวระบุรอบในหัวเรื่องหรือเนื้อหา เพื่อใช้ตรวจว่าอีเมลเป็นของรอบนั้น
5. เรียกปลายทาง OTP พร้อมตัวกรอง เปลี่ยนผู้ส่งและหัวเรื่องตัวอย่างให้ตรงกับระบบทดสอบของคุณ คำขอนี้มี since_minutes=5 ซึ่งเป็นพารามิเตอร์ที่ปลายทางรองรับ ส่วนการตัดสินว่าเป็นรหัสของรอบปัจจุบันให้ตรวจข้อความต้นทางในขั้นถัดไป

curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=no-reply@example.com' \
  --data-urlencode 'subject=UAT verification' \
  --data-urlencode 'since_minutes=5'

อย่าใช้ตัวกรองเพียงตัวเดียวเป็นหลักฐานว่ารหัสถูกต้อง ตัวอย่างเช่น ผู้ส่งรายเดียวอาจส่งอีเมลให้หลายรอบทดสอบ ส่วนหัวเรื่องทั่วไปอาจซ้ำกันทุกครั้ง

6. ตรวจข้อความต้นทางก่อนใช้รหัส เรียกรายการข้อความของกล่องเดียวกัน แล้วตรวจ id, received_at, from.address และ subject เทียบกับเวลาเริ่มรอบและบริบทของชุดทดสอบ

curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'from=no-reply@example.com'

หากต้องอ่านเนื้อหา ให้ตั้ง $MESSAGE_ID เป็น id ของข้อความที่กำลังตรวจ แล้วเรียกรายละเอียดข้อความ

curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

รายละเอียดข้อความมี body.text และ body.html ให้ตรวจเนื้อหา อย่าถือว่าข้อความที่อ่านแยกมานี้ตรงกับผลจากปลายทาง OTP โดยอัตโนมัติ ต้องตรวจรหัสและบริบทให้สัมพันธ์กัน หากมีหลายข้อความที่แยกไม่ออกว่าเป็นของรอบใด ให้หยุดรอบนั้นแทนการเดา

ก่อนใช้รหัส ให้เทียบ received_at กับเวลาเริ่มรอบ ตรวจผู้ส่ง หัวเรื่อง และเนื้อหา แล้วตรวจสถานะที่ชุดทดสอบเก็บไว้ว่าข้อความนี้ยังไม่เคยถูกใช้ ดูรายการปลายทางและสิทธิ์ประกอบได้ในเอกสาร API ของ Mailera

จะรออีเมลโดยไม่ใช้รหัสเก่าหรือรหัสข้ามรอบได้อย่างไร?

ให้ชุดทดสอบเป็นผู้ตัดสินว่ารหัสพร้อมใช้หรือไม่ อย่าให้การพบตัวเลขจากอีเมลเป็นเงื่อนไขสำเร็จเพียงอย่างเดียว

กำหนดเวลารอสูงสุดตั้งแต่เริ่มรอบ และเว้นช่วงก่อนเรียก API ซ้ำทุกครั้ง เมื่อครบกำหนดให้หยุดพร้อมเหตุผล เช่น ยังไม่พบข้อความที่ตรงกับรอบ หรือมีข้อความที่กำกวม ไม่ควรวนรอโดยไม่มีกำหนด และไม่ควรย้อนกลับไปใช้รหัสเก่าเพื่อให้การทดสอบผ่าน

เก็บสถานะของข้อความที่ใช้แล้วในชุดทดสอบ โดยอ้างอิง mailbox_id คู่กับ id จากรายการข้อความ เมื่อพบข้อความเดิมอีกครั้งให้ปฏิเสธการนำกลับมาใช้ อย่าใช้เพียงค่า is_unread เป็นตัวระบุรอบ เพราะสิ่งที่คุณต้องการตรวจคือความสัมพันธ์กับการขอรหัส ไม่ใช่สถานะการอ่าน

เวลาได้รับข้อความก็เป็นเพียงเงื่อนไขหนึ่ง ควรตรวจร่วมกับผู้ส่ง หัวเรื่อง และตัวระบุรอบจากระบบทดสอบ ถ้าไม่มีข้อมูลให้แยกรอบได้ชัด ให้รันทดสอบทีละรอบต่อกล่อง หรือแยกกล่องสำหรับงานที่ทำพร้อมกัน อย่าให้หลายงานขอรหัสชนกันแล้วเลือกอีเมลล่าสุดร่วมกัน

Mailera รับอีเมล Microsoft ผ่าน Graph change notifications และมีการตรวจเบื้องหลังเป็นระยะสำรองไว้ ดูกลไกการแจ้งเตือนการเปลี่ยนแปลงข้อความของ Graph ที่เอกสารของ Microsoft ชุดทดสอบยังต้องมีสถานะรอและเงื่อนไขหยุดของตัวเอง

หากเลือกเรียก Graph โดยตรงและได้รับ 429 Too Many Requests ให้รอตาม Retry-After ก่อนลองใหม่ หากไม่มี header นี้ Microsoft แนะนำ exponential backoff ตามแนวทางจัดการ throttling ของ Graph ข้อนี้เป็นพฤติกรรมของ Graph ไม่ใช่ข้อกำหนดรูปแบบการตอบกลับของ Mailera

ข้อผิดพลาดที่พบบ่อย: ทำไม API จึงไม่พบ OTP?

เริ่มจากตรวจว่าข้อความอยู่ที่ใดและกล่องยังเชื่อมต่อได้หรือไม่ ก่อนแก้กติกาแยกรหัส

สำหรับ Microsoft ปลายทางนี้ตรวจการลงชื่อเข้าใช้โดยตรง:

curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

หากต้องตรวจตำแหน่งข้อความ ให้ใช้ GET /mailboxes/{id}/placement ซึ่งรับ from, subject และ since_minutes เช่นเดียวกับปลายทาง OTP หรืออ่านรายการข้อความโดยกำหนด folder=junk อย่าใช้ผลจากปลายทาง OTP เพียงอย่างเดียวเพื่อตัดสินว่าไม่มีข้อความอยู่ในโฟลเดอร์อีเมลขยะ

เมื่อต้องสั่งซิงก์ ใช้ POST /mailboxes/{id}/sync ด้วยคีย์สิทธิ์ sync แล้วตรวจรายการข้อความอีกครั้ง การส่งคำขอซิงก์ไม่ได้หมายความว่าชุดทดสอบควรเดินหน้าต่อทันที

Mailera แสดงว่าอีเมลอยู่ใน Inbox หรือ Junk และย้ายข้อความออกจากโฟลเดอร์อีเมลขยะได้ แต่ไม่ทำให้ผู้ให้บริการเชื่อถือผู้ส่งในครั้งถัดไป และไม่รับประกันการเข้า Inbox การแก้ปัญหาจึงต้องแยกให้ออกระหว่างข้อความยังไม่ถึง ข้อความอยู่ผิดโฟลเดอร์ และเลือกข้อความผิดรอบ

ควรป้องกันคีย์ รหัสยืนยัน และเนื้อหาอีเมลอย่างไร?

เก็บ $MAILERA_API_KEY ในตัวแปรสภาพแวดล้อมที่ระบบทดสอบได้รับจากที่เก็บความลับ อย่าฝังคีย์ในซอร์สโค้ด และอย่าเปิดการบันทึกคำขอที่พิมพ์ Authorization ออกมา คำสั่งอ่านข้อความอาจแสดงรหัสและเนื้อหาอีเมลในผลลัพธ์ จึงควรระวังไม่ให้ log ของ CI บันทึกผลลัพธ์เต็มรูปแบบไว้โดยไม่จำเป็น

เก็บเฉพาะข้อมูลวิเคราะห์ที่จำเป็น เช่น ข้อความผ่านเงื่อนไขเวลาแล้วหรือยัง และถูกปฏิเสธเพราะเหตุใด โดยไม่เก็บค่ารหัสไว้ในรายงาน

ใช้คีย์สิทธิ์ read ที่จำกัดกลุ่มทดสอบ กำหนดวันหมดอายุ และเพิกถอนเมื่อจบงาน Mailera รองรับการเพิกถอนคีย์ได้ทุกเมื่อ โดยคำขอหลังเพิกถอนจะถูกปฏิเสธทันที รายละเอียดเพิ่มเติมอยู่ที่หน้าความปลอดภัยของ Mailera

หากส่งเนื้อหาอีเมลต่อให้ AI agent ต้องถือว่าอีเมลเป็นข้อมูลที่ไม่น่าเชื่อถือ ไม่ใช่คำสั่ง ห้ามให้ agent ทำตามข้อความที่สั่งเปิดเผยคีย์ เปลี่ยนสิทธิ์ หรือส่งข้อมูลออกไป ตัวอย่างนี้ไม่ต้องมีสิทธิ์ส่งอีเมล หากภายหลังเพิ่มการส่ง ต้องให้ผู้ใช้ยืนยันก่อนส่งด้วย ดูภาพรวมช่องทางเชื่อมต่อสำหรับแอปและ agent ได้ที่หน้าMailera สำหรับนักพัฒนา