ดึง OTP จาก Hotmail ผ่าน API โดยไม่หยิบรหัสผิดคำขอ

การอ่าน OTP ไม่ใช่การตรวจสอบ OTP

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

Mailera เชื่อม Hotmail ผ่าน Microsoft Graph ด้วย OAuth และมี GET /mailboxes/{id}/otp สำหรับดึงรหัสล่าสุด เส้นทางนี้เป็น API ของ Mailera ไม่ใช่ endpoint ของ Microsoft Graph โดยตรง หากต้องการภาพรวมที่ไม่จำกัดเฉพาะ Hotmail ดูคู่มืออ่าน OTP จากกล่องจดหมายของคุณ

แยกปัญหาสองอย่างนี้ก่อนเริ่ม: ถ้าคุณเข้า Hotmail ได้แต่อีเมลรหัสทดสอบไม่มา ให้ตรวจตามขั้นตอนด้านล่าง แต่ถ้าคุณเข้า Hotmail ไม่ได้เพราะไม่มีโทรศัพท์รับรหัส นั่นเป็นงานกู้บัญชี ไม่ใช่งานอ่านอีเมลผ่าน API

ก่อนดึงรหัส ต้องเชื่อม Hotmail และให้สิทธิ์อะไรบ้าง?

ใช้กล่องจดหมายทดสอบของคุณเอง แยกจากอีเมลส่วนตัว และใช้เฉพาะกับระบบที่คุณได้รับอนุญาตให้ทดสอบ การกำหนดตั้งแต่ต้นว่าจะใช้กล่องจดหมายใดบ้างช่วยให้เลือกขอบเขตคีย์ได้ตรงกับงาน

1. เชื่อม Hotmail ด้วย OAuth

ให้สมาชิกที่มีบทบาท Admin หรือ Leader เปิด กล่องจดหมาย → เพิ่มกล่องจดหมาย → ลงชื่อเข้าใช้ด้วย Microsoft แล้วอนุญาตการเข้าถึงที่หน้า Microsoft ตรวจบัญชีที่กำลังอนุญาตให้ตรงกับ Hotmail ทดสอบก่อนดำเนินการต่อ

การเชื่อม Microsoft ใน Mailera ไม่ใช้รหัสผ่านสำหรับแอป (app password) ดูรายละเอียดได้ที่การเชื่อม Outlook และ Hotmail หากคุณตั้งค่าผู้ให้บริการอื่นด้วย อย่านำขั้นตอนจากคู่มือรหัสผ่านสำหรับแอป มาใช้แทน OAuth ของ Microsoft

ตามเอกสารการอนุญาตในนามผู้ใช้ของ Microsoft ผู้ใช้ต้องอนุญาตให้แอปทำงานในนามของตน และการเรียก Microsoft Graph ต้องใช้ access token จาก Microsoft identity platform

2. สร้างคีย์สำหรับอ่านกล่องทดสอบเท่านั้น

เปิด การตั้งค่า ไปยังส่วนคีย์ API แล้วเลือก สร้าง API key ตั้ง ชื่อที่สื่อความหมาย ให้ระบุงานทดสอบได้ จากนั้นเลือก ขอบเขตกล่องจดหมาย เป็นกลุ่มที่ใช้ทดสอบ ติ๊กเฉพาะสิทธิ์ Read (ตรงกับ scope read ที่ endpoint ต้องใช้) และกำหนด ระยะเวลาที่ใช้ได้ ให้เหมาะกับงาน

คัดลอกคีย์ไปเก็บในระบบจัดการความลับทันที เพราะ Mailera แสดงค่าคีย์ใหม่เพียงครั้งเดียว ไม่ต้องให้สิทธิ์ send, manage หรือ share สำหรับงานอ่านรหัสอย่างเดียว

สิทธิ์ read ของคีย์ Mailera เป็นคนละชั้นกับสิทธิ์ OAuth ของ Microsoft Graph ไม่ใช่ชื่อสิทธิ์เดียวกัน

สำหรับแอปที่เรียก Microsoft Graph โดยตรง Microsoft แนะนำให้ขอเฉพาะสิทธิ์ที่จำเป็นเท่านั้น ดูเอกสารอ้างอิงสิทธิ์ Microsoft Graph

3. เลือกกล่องจดหมายให้ถูก แล้วตรวจการเชื่อมต่อ

ให้ระบบจัดการความลับส่งคีย์เข้าตัวแปรสภาพแวดล้อม MAILERA_API_KEY จากนั้นเรียกรายการกล่องจดหมาย:

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

ตรวจ email และ provider ในแต่ละรายการ แล้วเลือก id ของ Hotmail ที่ต้องการไปใส่ตัวแปร MAILBOX_ID อย่าเลือกรายการแรกเพียงเพราะเป็นกล่องจดหมาย Microsoft เหมือนกัน หากมีหลายหน้า ให้ตรวจรายการต่อด้วย limit และ offset

จากนั้นตรวจว่าการลงชื่อเข้าใช้ยังทำงานอยู่:

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

สำหรับ Microsoft เส้นทาง /status ตรวจการลงชื่อเข้าใช้โดยตรง ส่วน last_sync_at ในรายการกล่องจดหมายใช้ประกอบการดูว่าซิงก์ล่าสุดเมื่อใด อย่าใช้เวลาซิงก์แทนผลตรวจการเชื่อมต่อ ดูโครงสร้างการใช้งาน REST เพิ่มเติมได้ที่หน้า Mailera สำหรับนักพัฒนา

จะเรียก API ให้ได้รหัสจากอีเมลทดสอบที่ต้องการอย่างไร?

4. เริ่มคำขอรหัสและบันทึกเวลา

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

ถ้าคุณควบคุมระบบส่งอีเมลทดสอบได้ ให้ตั้งหัวเรื่องที่แยกแต่ละรอบทดสอบออกจากกันได้ชัดเจน และหลีกเลี่ยงการเปิดหลายคำขอพร้อมกันในกล่องเดียวระหว่างตรวจปัญหา วิธีนี้ทำให้ไล่ความสัมพันธ์ระหว่างคำขอกับอีเมลได้ง่ายกว่าการขอรหัสซ้ำไปเรื่อย ๆ

5. เรียก /otp พร้อมพารามิเตอร์

GET /mailboxes/{id}/otp ใช้สิทธิ์ read และรับพารามิเตอร์ from, subject และ since_minutes นอกเหนือจาก id ของกล่องจดหมาย:

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

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

ใช้คำสั่งนี้ในสภาพแวดล้อมส่วนตัวที่ไม่เก็บผลลัพธ์ลงบันทึกการทำงาน เพราะผลตอบกลับอาจมีรหัสจริง ในระบบทดสอบอัตโนมัติ ให้รับผลตอบกลับเข้าหน่วยความจำแทนการพิมพ์ลงคอนโซล

อย่าใช้ผู้ส่งและหัวเรื่องแทนการจับคู่คำขอ หากมีหลายคำขอจากผู้ส่งเดียวกันและหัวเรื่องเดียวกัน ให้ตรวจรายการอีเมลประกอบด้วย GET /mailboxes/{id}/messages โดยดู id, from.address, subject และ received_at อย่านำฟิลด์ของรายการอีเมลไปสมมติว่าเป็นโครงสร้างผลตอบกลับของ /otp; ใช้เอกสาร API ของ Mailera สำหรับแต่ละ operation

6. ส่งรหัสกลับไปยังขั้นตอนที่ร้องขอไว้

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

หากต้องเรียกตรวจซ้ำ ให้เว้นช่วงและกำหนดจำนวนครั้งสูงสุดไว้ Mailera จำกัด API ที่ 300 คำขอต่อนาทีต่อคีย์ จึงไม่ควรให้แต่ละงานทดสอบวนเรียกโดยไม่คำนึงถึงงานอื่นที่ใช้คีย์เดียวกัน

ข้อผิดพลาดที่พบบ่อย: ทำไมไม่พบ OTP หรือได้รหัสผิด?

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

ใช้ /placement ตรวจว่าอีเมลอยู่ในกล่องขาเข้าหรืออีเมลขยะ โดยเลือกกล่องและพารามิเตอร์ให้สอดคล้องกับการอ่าน OTP:

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

ถ้าต้องตรวจข้อความในโฟลเดอร์อีเมลขยะโดยตรง ใช้ GET /mailboxes/{id}/messages พร้อม folder=junk หรือเปิดโฟลเดอร์นั้นใน Mailera การตรวจตำแหน่งข้อความกับการดึงรหัสเป็นคนละงาน อย่าตีความผลจากงานหนึ่งแทนอีกงานหนึ่ง

สำหรับแอปที่เรียก Microsoft Graph โดยตรง มี API สำหรับแสดงข้อความในโฟลเดอร์ที่ระบุ

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

หากต้องสั่งซิงก์เอง POST /mailboxes/{id}/sync ต้องมีสิทธิ์ sync เพิ่ม คีย์ read อย่างเดียวใช้สั่งไม่ได้ เช่นเดียวกับการกด ไม่ใช่อีเมลขยะ ในหน้าข้อความ ซึ่งต้องมีสิทธิ์ move

จะเก็บรหัสและคีย์ให้ปลอดภัยระหว่างทดสอบได้อย่างไร?

เก็บคีย์ในระบบจัดการความลับ ไม่ใส่ในซอร์สโค้ดหรือ URL ส่งผ่าน header Authorization: Bearer และปิดบังทั้งคีย์ รหัส OTP และข้อมูลบัญชีในภาพหน้าจอ แนวทางนี้สอดคล้องกับ RFC 6750 เรื่อง bearer token ซึ่งระบุให้ป้องกัน token จากการเปิดเผยทั้งขณะเก็บและขณะส่ง

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

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

ข้อจำกัดที่ต้องเผื่อไว้ในงานทดสอบ

Mailera เชื่อมกล่องจดหมายที่คุณมีอยู่แล้ว ไม่สร้างกล่องจดหมายหรือที่อยู่อีเมลใหม่ ขั้นตอนนี้จึงเริ่มจาก Hotmail ที่คุณสามารถอนุญาตการเข้าถึงได้ ไม่ใช่วิธีใช้แทนการเข้าสู่บัญชี Microsoft

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

สำหรับผลทดสอบ ให้แยกสถานะ “อ่านรหัสได้” ออกจาก “ระบบต้นทางรับรหัสแล้ว” เสมอ การเลือกรหัสล่าสุดไม่ควรเป็นเกณฑ์ผ่านของขั้นตอนยืนยันตัวตน