일회용 이메일 API: 개발자를 위한 가이드

웹 받은편지함은 사람에게는 훌륭하지만, 테스트와 자동화에는 일회용 이메일 API가 필요합니다. 버리는 주소를 만들고, 거기에 도착한 메일을 읽고, 다 쓰면 정리하는 일을 모두 코드로 처리하는 방법 말입니다. 이 글에서는 그 구성 요소들과, MoeMail의 임시 이메일 OpenAPI로 이를 연결하는 방법을 살펴봅니다.

웹 받은편지함 대신 API를 쓰는 이유

가입, 이메일 인증, 비밀번호 재설정 흐름은 종단 간 테스트가 가장 까다로운 축에 듭니다. 인증 단계가 앱을 벗어나 받은편지함에 도달하기 때문입니다. 일회용 이메일 API는 그 고리를 닫아 줍니다. 테스트가 새 받은편지함을 발급받고, 흐름을 실행한 뒤, API를 폴링해 인증 메시지를 받아 링크나 코드를 추출합니다. 여러 사람이 공유하는 받은편지함을 어지럽힐 일 없이, 결정적으로 동작합니다.

API 키 인증

MoeMail은 X-API-Key 헤더로 전달되는 API 키로 프로그래밍 방식 요청을 인증합니다. 로그인 후 프로필에서 키를 발급받아 모든 요청에 붙이면 됩니다. 키는 이메일 및 설정 엔드포인트로 범위가 제한되고 계정의 월별 할당량을 적용받으므로, 비밀 값처럼 다루고 유출되면 교체하세요.

핵심 동작

• 메일함 만들기 — 원하는 만료 시점으로 무작위 또는 직접 정한 새 주소를 요청합니다.
• 메시지 목록 조회 — 메일함을 폴링해 새로 받은 이메일을 가져옵니다.
• 메시지 읽기 — 개별 메시지의 헤더, 텍스트, HTML 본문을 가져옵니다.
• 만료되도록 두기 — 아무것도 하지 않으면 메일함과 메시지가 자동으로 정리됩니다.

가장 단순한 폴링 호출은 키를 헤더에 담아 이메일 엔드포인트로 보내는 형태입니다. 예: curl -H "X-API-Key: YOUR_KEY" https://moemail.app/api/emails. 정확한 요청·응답 형식은 OpenAPI 정의에 문서화되어 있습니다.

Webhook: 폴링을 멈추세요

폴링도 동작하지만 지연을 더하고 요청을 낭비합니다. MoeMail은 메시지가 도착하는 순간 webhook을 발사할 수 있으므로, 테스트나 백엔드가 반복문을 도는 대신 즉시 반응합니다. webhook을 테스트 하니스가 제어하는 엔드포인트로 향하게 하고, 페이로드를 검증한 뒤, 메시지가 도착하자마자 대기 중인 단계를 해소하세요. 핸들러는 빠르게, 몇 초 안에 응답해야 합니다. 느리거나 2xx가 아닌 응답은 재시도를 유발하기 때문입니다.

속도 제한과 할당량

API 사용량은 계정의 월별 OpenAPI 할당량에서 차감됩니다. 큰 테스트 모음에서는 가능한 경우 단언 사이에 메일함을 재사용하고, 폴링을 한데 묶고, 빡빡한 폴링 반복보다 webhook을 선호하세요. 여유가 더 필요하면 상위 등급과 상점 할당량으로 한도를 높이거나, 직접 인스턴스를 운영하세요(셀프 호스팅 vs 호스팅형 임시 이메일 참고).

테스트에 적용하기

Playwright든 Cypress든 Selenium이든 패턴은 같습니다. 만들기·폴링·읽기 호출을 작은 헬퍼(픽스처나 커스텀 명령)로 감싸고, 테스트 시작 시 받은편지함을 발급받고, UI를 인증 단계까지 진행한 뒤, 헬퍼를 통해 메시지를 기다립니다. 실행마다 고유한 주소를 받으므로 테스트는 서로 격리되어 병렬로 안전하게 돌아갑니다.

다음 단계

전체 API 문서를 읽고, 프로필에서 키를 받아, 만들기·폴링 한 번을 직접 시도해 보세요. 그런 다음 종단 간으로 자동화하세요. 이메일 인증 테스트 자동화 방법과 webhook으로 수신 이메일 받기를 참고하세요. 개념이 처음이라면 임시 이메일이란?부터 시작하거나, 대시보드에서 메일함을 만들어 API가 무엇을 돌려주는지 직접 확인해 보세요.