ดึง OTP จาก Gmail ผ่าน API สำหรับทดสอบแอป

ดึง OTP จาก Gmail ผ่าน API ได้อย่างไร?

เชื่อมต่อกล่อง Gmail ที่คุณใช้ทดสอบกับ Mailera แล้วเรียก GET /mailboxes/{id}/otp ด้วยคีย์ที่มีสิทธิ์ read ปลายทางรองรับพารามิเตอร์ from, subject และ since_minutes ก่อนนำรหัสไปใช้ ให้ตรวจผู้ส่ง หัวเรื่อง และเทียบ received_at ในรายการข้อความกับเวลาเริ่มคำขอทดสอบ

OTP ในที่นี้คือรหัสยืนยันที่แอปส่งเข้ากล่อง Gmail ของคุณเพื่อใช้ในขั้นตอนทดสอบ ไม่ใช่การรับรหัสทาง SMS และไม่ใช่ขั้นตอนยืนยันเพื่อเข้าบัญชี Google

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

Mailera เชื่อมต่อกล่องจดหมายที่มีอยู่แล้ว แล้วให้แอปอ่านผ่าน API หากต้องการภาพรวมที่ไม่จำกัดเฉพาะ Gmail ดูคู่มืออ่าน OTP จากกล่องจดหมายของคุณ ส่วนขั้นตอนต่อไปนี้เน้น Gmail และการเลือกข้อความให้ตรงรอบทดสอบ

ก่อนเชื่อมต่อ Gmail ต้องเตรียมอะไรบ้าง?

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

Google กำหนดให้เปิดการยืนยันสองขั้นตอนก่อนใช้รหัสผ่านสำหรับแอป (app password) ดูเงื่อนไขรหัสผ่านสำหรับแอปของ Google และวิธีเปิดการยืนยันสองขั้นตอน ก่อนเริ่มเชื่อมต่อ

หากไม่เห็นตัวเลือกสร้างรหัสผ่านสำหรับแอป ให้ตรวจว่าบัญชีใช้เฉพาะคีย์ความปลอดภัยสำหรับการยืนยันสองขั้นตอนหรือเปิด Advanced Protection อยู่หรือไม่ บัญชีที่ทำงาน สถานศึกษา หรือองค์กรก็อาจไม่มีตัวเลือกนี้ สำหรับ Google Workspace ให้ตรวจนโยบายกับผู้ดูแล หากเปิดการยืนยันสองขั้นตอนไม่ได้บนบัญชีองค์กรหรือสถานศึกษา Google แนะนำให้ติดต่อผู้ดูแลระบบ ไม่ควรลดระดับความปลอดภัยของบัญชีเพื่อให้เชื่อมต่อได้

ข้อมูลลับสองตัวนี้ทำหน้าที่ต่างกัน:

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

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

1. เพิ่มกล่อง Gmail ทดสอบ

ให้สมาชิกที่มีบทบาท Admin หรือ Leader เปิด กล่องจดหมาย → เพิ่มกล่องจดหมาย เลือกแท็บ กล่องจดหมายเดียว แล้วกรอก Gmail ของคุณในช่อง ที่อยู่อีเมล

ตรวจว่าผู้ให้บริการที่ระบบตรวจพบคือ Gmail หากต้องเลือกเอง ให้ใช้ส่วน หรือเลือกผู้ให้บริการ แล้วกด ดำเนินการต่อ

2. ทดสอบการเชื่อมต่อ

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

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

3. สร้างคีย์เฉพาะกลุ่มทดสอบ

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

ใน ขอบเขตกล่องจดหมาย เลือกกลุ่มทดสอบกลุ่มเดียวที่กล่อง Gmail นี้อยู่ เลือกสิทธิ์ “Read” ซึ่งตรงกับ scope read และกำหนด ระยะเวลาที่ใช้ได้ ให้เหมาะกับงาน ไม่เพิ่มสิทธิ์ “Send messages” หรือ “Manage mailboxes” หากสคริปต์มีหน้าที่อ่านรหัสเท่านั้น

เมื่อเห็น สร้าง API key แล้ว — คัดลอกตอนนี้ ให้บันทึกคีย์ในระบบจัดการข้อมูลลับ เพราะค่าคีย์จะแสดงเพียงครั้งเดียว จากนั้นส่งค่าเข้าสู่สภาพแวดล้อมของสคริปต์เป็น $MAILERA_API_KEY ดูแนวทางเชื่อมต่อแอปเพิ่มเติมได้ที่หน้าสำหรับนักพัฒนา

4. จับคู่ที่อยู่อีเมลกับ mailbox ID

เรียกรายการกล่องจดหมายด้วยคีย์ที่สร้างไว้:

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

ในรายการ data ให้หา email ที่ตรงกับ Gmail ทดสอบของคุณ แล้วนำ id ของรายการนั้นไปตั้งเป็น $MAILBOX_ID อย่าเลือกสมาชิกตัวแรกของรายการโดยไม่ตรวจที่อยู่อีเมล

ตรวจ group_id ด้วยว่ากล่องอยู่ในกลุ่มที่ตั้งใจใช้ หากไม่พบกล่อง ให้ตรวจว่าขอบเขตกล่องจดหมายของคีย์ครอบคลุมกลุ่มนั้นหรือไม่ หากต้องสร้างคีย์ใหม่ ให้เลือกเฉพาะกลุ่มทดสอบที่ถูกต้องและสิทธิ์ “Read”

เรียก API เพื่อเลือก OTP ที่ต้องการอย่างไร?

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

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

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

6. เรียกปลายทาง OTP พร้อมตัวกรอง

เปลี่ยนผู้ส่งและหัวเรื่องในตัวอย่างให้ตรงกับอีเมลจากแอปทดสอบของคุณ ที่อยู่ verification@example.invalid เป็นเพียงค่าตัวอย่าง:

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

พารามิเตอร์ from, subject, since_minutes เป็นของ Mailera endpoint นี้โดยเฉพาะ ไม่ใช่ไวยากรณ์ค้นหาของ Gmail จึงไม่ควรใส่คำค้นแบบ Gmail ปะปน หากต้องการรายละเอียดข้อกำหนดของคำขอและผลลัพธ์ ให้ดูเอกสาร API ของ Mailera ก่อนเขียนโค้ดอ่านผลลัพธ์ อย่าสมมติชื่อฟิลด์จาก API ของบริการอื่น

7. ตรวจข้อความก่อนนำรหัสไปใช้

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

curl --fail-with-body --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'from=verification@example.invalid'

ผลรายการข้อความมี mailbox_id, from.address, subject, received_at และ folder เทียบ received_at กับเวลาเริ่มคำขอที่บันทึกไว้ และตรวจข้อมูลอื่นประกอบ แทนการเห็นตัวเลขในข้อความแล้วส่งเข้าแบบฟอร์มทันที หากมีหลายข้อความที่ยังแยกไม่ออกว่าเป็นของคำขอใด ให้หยุดรอบนั้นและเริ่มคำขอที่ระบุได้ชัดเจนกว่า

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

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

ข้อผิดพลาดที่พบบ่อยเมื่อไม่พบ OTP มีอะไรบ้าง?

เริ่มจากแยกให้ออกว่าไม่มีอีเมลเข้ากล่อง หรือมีอีเมลแล้วแต่การเลือกข้อความไม่ตรง ตรวจรายการข้อความก่อนแก้พารามิเตอร์ในคำขอ

ปลายทาง GET /mailboxes/{id}/placement ใช้ตรวจว่าอีเมลอยู่ในกล่องจดหมายเข้าหรือสแปม และรองรับ from, subject, since_minutes หากต้องย้ายข้อความออกจากสแปม สิทธิ์ read อย่างเดียวไม่พอ ต้องใช้คีย์ที่มีสิทธิ์ “Move messages” (scope move) เรียก POST /mailboxes/{id}/unspam หรือ POST /mailboxes/{id}/messages/{msgId}/move แยกต่างหาก

สำหรับ Gmail ค่าใน GET /mailboxes/{id}/status อิงการซิงก์ล่าสุด ไม่ใช่การทดลองลงชื่อเข้าใช้ Google ใหม่ทุกครั้งที่เรียก หากต้องการสั่งซิงก์ ใช้ POST /mailboxes/{id}/sync ด้วยคีย์ที่มีสิทธิ์ “Sync” (scope sync) แยกจากคีย์อ่านตามความจำเป็น การสั่งซิงก์ไม่ใช่การสั่งให้แอปต้นทางส่งอีเมล

หากปัญหาเริ่มหลังเปลี่ยนรหัสผ่านบัญชี Google ให้ตรวจรหัสผ่านสำหรับแอปก่อน Google แจ้งว่าการเปลี่ยนรหัสผ่านบัญชีจะเพิกถอนรหัสผ่านสำหรับแอปของบัญชีนั้น

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

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

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

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

ขอบเขตที่ Mailera ไม่ได้จัดการให้

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

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