가입 폼을 위한 실시간 이메일 유효성 검사 API
사용자가 주소를 제출하는 순간 유효성을 검사합니다. 호출 한 번으로 메일 서버와 메일함이 있는지 확인하고, 일회용 주소와 역할 기반 주소 플래그도 받습니다. 어떤 주소를 받을지는 직접 정합니다. 이 이메일 유효성 검사 API는 잘못된 데이터를 입력 단계에서 막아, 가짜 계정이 데이터베이스에 들어오지 않게 합니다.
// 1. Receive submitted form data
const { email } = req.body;
// 2. Validate via API
const { data } = await checkEmail(email);
// 3. Make real-time form decision
if (data.status === 'undeliverable') {
return res.status(400).json({ error: 'Please enter a valid, active email address.' });
}
if (data.details.attributes.disposable) {
return res.status(400).json({ error: 'Temporary or disposable emails are not allowed.' });
}
// 4. Proceed with account registration
await createUser({ email });무료 크레딧 1,000개, 신용카드 불필요. 크레딧 유효기간 없음.
정규식만으로는 이메일 유효성 검사가 되지 않는 이유
정규식(regular expression)은 문자열의 구조만 확인합니다. @ 기호가 있는지, 도메인 형식이 그럴듯한지, 문자가 표준 ASCII 범위 안에 있는지만 봅니다. 정규식은 입력값이 이메일 주소처럼 보이는지만 알려 줍니다. 그 주소로 실제로 메시지를 받을 수 있는지는 알려 주지 않습니다.
user@example.com, asdf12345@gmail.com 같은 주소는 RFC를 따르는 모든 정규식을 통과합니다. 하지만 한쪽 도메인에는 작동하는 메일 서버가 없을 수 있고, 다른 쪽 메일함은 존재하지 않을 수 있습니다.
이 이메일 유효성 검사 API(JSON 응답)는 정규식보다 훨씬 많은 것을 확인합니다. 요청 한 번으로 DNS 레코드를 확인하고, MX 호스트를 조회하고, 수신 메일 서버에 연결해 메일함 응답을 테스트하고, 도메인을 대규모 일회용 도메인 목록과 대조합니다.
엄격한 정규식 패턴은 정상 주소를 잘못 거부하기도 합니다. 직접 만든 정규식은 .studio나 .cloud 같은 흔하지 않은 최상위 도메인, 올바른 국제 문자, 특이한 문장 부호가 들어간 정상 주소를 거부하는 경우가 많습니다. 이 API는 RFC 5322 문법을 자동으로 처리하므로, 코드베이스에서 깨지기 쉬운 정규식 라이브러리를 관리할 필요가 없습니다.
문법 검사
외부 네트워크 조회 전에 기본 오타, 빠진 TLD, 허용되지 않는 문장 부호, 공백 문제를 잡아냅니다.
DNS 및 MX 확인
도메인 등록 상태를 확인하고, 들어오는 메시지를 받도록 설정된 메일 교환 서버(MX)를 찾습니다.
메일함 검사
원격 메일 서버와 직접 통신해 해당 메일함이 있고 메일을 받을 수 있는지 확인합니다.
가입 시 차단, 표시, 허용할 주소
가입 요건은 회사마다 다릅니다. B2B 기업용 SaaS는 회사 이메일만 받을 수 있고, 소비자용 소셜 앱은 개인 Gmail 주소도 받습니다. 실제 API 응답 속성을 기준으로 한 권장 판단표는 다음과 같습니다.
| API 결과 | 필드 조건 | 폼에서 할 일 |
|---|---|---|
| 무효 | status === "undeliverable" | 바로 차단합니다. 표시 문구: “사용 중인 올바른 이메일 주소를 입력해 주십시오.” |
| 일회용 | details.attributes.disposable === true | 차단하거나 다른 주소를 요청합니다. 표시 문구: “임시 이메일 주소는 사용할 수 없습니다.” |
| 역할 계정 | details.attributes.role_account === true | 허용하되 B2B 폼에서는 표시합니다. 계정 담당자에게 알리거나 일반 리드 분류로 보냅니다. |
| 무료 이메일 | details.attributes.free_email === true | B2C 앱에서는 허용합니다. B2B 데모 신청 폼이나 체험판 폼에서는 회사 이메일을 요구합니다. |
| 캐치올 | details.attributes.catch_all === true | catch_all_verdict 값을 확인합니다. “valid”이면 허용, “invalid”이면 차단, null이면 가입을 허용합니다. |
| 알 수 없음 | status === "unknown" | 받아들이고 나중에 다시 검사합니다(크레딧 환불). 정상 사용자가 차단되지 않도록 실패 시 허용(fail open) 방식으로 처리합니다. |
가입 폼에 이메일 유효성 검사 추가하기
실시간 유효성 검사를 안전하게 연동하려면 다음 네 단계를 따르십시오. 요청에는 비공개 API 키가 필요하므로 검사는 백엔드 서버에서 실행하십시오.
실패 시 허용 방식이 중요한 이유: 가입 폼은 지연에 민감합니다. 외부 API 호출에 네트워크 지연이 생겼을 때 폼을 막으면 실제 고객을 잃을 수 있습니다. 제한 시간을 짧게 두고 시간이 지나면 가입을 자동으로 진행하면, 정상 사용자를 돌려보내지 않습니다. 백엔드는 그 주소를 나중에 백그라운드에서 검사하도록 대기열에 넣습니다.
폼이 백엔드로 전송
방문자가 가입 정보를 제출하면 브라우저가 이메일 주소를 애플리케이션 엔드포인트로 보냅니다.
백엔드가 유효성 검사 API 호출
서버가 환경 변수에 저장된 비공개 키로 Giggal에 동기 POST 요청을 보냅니다.
백엔드가 판단표 적용
JSON 속성을 파싱합니다. 이메일이 일회용이거나 전송 불가이면 브라우저에 분명한 오류 메시지를 반환합니다.
시간 초과 시 허용
외부 네트워크 통신이 시간 초과되면 실패 시 허용 방식으로 처리합니다. 가입을 받아들이고, 나중에 검증할 백그라운드 작업을 대기열에 넣습니다.
구현 코드 예제
// server.js (Express Route)
const timeoutMs = 5000; // adjust to what your form can tolerate
app.post('/api/signup', async (req, res) => {
const { email, password } = req.body;
try {
const apiRes = await fetch('https://api.giggal.ai/v1/verify', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.GIGGAL_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(timeoutMs), // fail-open timeout
});
const result = await apiRes.json();
if (result.success) {
const { status, details } = result.data;
// Decision checks
if (status === 'undeliverable') {
return res.status(400).json({ error: 'This email address does not exist.' });
}
if (details.attributes.disposable) {
return res.status(400).json({ error: 'Disposable email addresses are not accepted.' });
}
}
} catch (err) {
// Fail open: log timeout and let user proceed
console.warn('Email check timed out, failing open:', err.message);
}
// Create user in database
const user = await db.users.create({ email, password });
return res.json({ success: true, userId: user.id });
});# app.py (Flask Route)
import os, requests
from flask import Flask, request, jsonify
app = Flask(__name__)
timeout_seconds = 5 # adjust to what your form can tolerate
@app.route("/api/signup", methods=["POST"])
def signup():
email = request.json.get("email")
try:
resp = requests.post(
"https://api.giggal.ai/v1/verify",
headers={"Authorization": f"Bearer {os.environ['GIGGAL_API_KEY']}"},
json={"email": email},
timeout=timeout_seconds # fail open on timeout
)
data = resp.json().get("data", {})
if data.get("status") == "undeliverable":
return jsonify({"error": "Email address is invalid."}), 400
if data.get("details", {}).get("attributes", {}).get("disposable"):
return jsonify({"error": "Disposable emails are prohibited."}), 400
except requests.exceptions.RequestException:
# Fail open: proceed with signup on timeout
pass
# Complete user registration
return jsonify({"success": True})// Frontend form submit handler
const form = document.querySelector('#signup-form');
form.addEventListener('submit', async (e) => {
e.preventDefault();
const email = document.querySelector('#email-input').value;
const res = await fetch('/api/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email }),
});
const payload = await res.json();
if (!res.ok) {
showFormError(payload.error); // Show friendly user feedback
} else {
redirectToDashboard();
}
});중요: 클라이언트 측 스크립트에서 Giggal API 엔드포인트를 직접 호출하지 마십시오. 인증 정보는 서버에 비공개로 보관하십시오.
일회용 주소와 가짜 가입 차단
임시 메일함은 제품 분석 데이터를 왜곡하고, 무료 체험 한도를 소모하며, 유료 고객으로 전환되지 않습니다. 이 서비스는 위험도가 높은 가입 패턴을 찾아 표시합니다.
일회용 메일함
100,000개가 넘는 임시 도메인 목록과 대조합니다. 일회용 메일함을 찾아내는 방법은 일회용 이메일 판별 도구에서 자세히 확인하십시오.
플러스 주소 감지
플러스 태그(user+trial@domain.com)로 만든 별칭을 표시해, 한 사용자가 체험판 계정을 여러 개 만드는 것을 막습니다.
회신 불가(No-Reply) 메일함 감지
받은 메일을 버리는 발송 전용 자동 메일함을 찾아내, 사용자가 응답할 수 없는 주소로 가입하지 못하게 합니다.
사용자 오타를 자동으로 고치지 않기
사용자 입력을 알리지 않고 바꾸지 마십시오(예: gnail.com을 gmail.com으로 자동 변경). 주소가 유효성 검사를 통과하지 못하면 분명한 메시지로 사용자에게 입력을 확인하도록 요청하십시오. 알리지 않고 고치면 계정 활성화 토큰이나 결제 영수증이 다른 사람에게 전달될 수 있습니다.
실시간 이메일 유효성 검사를 적용할 곳
제품에서 사용자가 폼을 제출하는 모든 곳에서 이메일 주소를 검사합니다.
회원 가입 폼
가입 스팸을 막고, 환영 이메일과 인증 링크가 실제 받은편지함에 도달하도록 돕습니다.
전자상거래 결제
배송 알림, 영수증, 주문 확인 메일이 전송 실패 없이 고객에게 도달하게 합니다.
리드와 데모 신청
경쟁사의 가짜 입력을 걸러내고, 영업 담당자에게 넘기기 전에 회사 도메인을 검증합니다.
뉴스레터 구독
구독 신청 단계에서 잘못된 입력과 봇 가입을 거부해 발송 도메인의 평판을 지킵니다.
웹훅 자동화
미리 만들어진 Zapier와 n8n 연동으로 폼 웹훅에서 유효성 검사를 자동으로 실행합니다.
계정 프로필 변경
기존 사용자가 프로필이나 결제 담당자 정보를 바꿀 때 새 이메일 주소를 검증합니다.
가입 시 사용하는 응답 필드
폼 유효성 검사 로직에 필요한 핵심 JSON 필드를 간단히 정리했습니다.
| JSON 필드 | 타입 | 가입 시 용도 |
|---|---|---|
| data.is_valid | boolean | 빠른 불리언 검사입니다. 도메인과 메일함 검증을 통과하면 true입니다. |
| data.status | string | 기본 전송 상태: "deliverable", "undeliverable", "unknown". |
| data.deliverability_score | number (0-100) | 메일함 응답, MX 안정성, 평판 검사를 기준으로 한 품질 점수입니다. |
| data.details.attributes.disposable | boolean | 도메인이 알려진 임시 또는 일회용 메일함 서비스이면 true입니다. |
| data.details.attributes.free_email | boolean | 개인용 이메일 제공업체(Gmail, Outlook)이면 true입니다. B2B 폼에서는 회사 도메인을 요구하십시오. |
| data.details.attributes.role_account | boolean | info@, admin@, support@ 같은 조직 주소이면 true입니다. |
| data.catch_all_verdict | "valid" | "invalid" | null | 캐치올 도메인을 같은 호출에서 판별합니다. 유효한 리드를 버리지 않고 살릴 수 있습니다. |
전체 엔드포인트 정의, 파라미터 스키마, 오류 코드는 전체 API 레퍼런스를 참고하십시오.
이메일 유효성 검사 API 요금
실행한 유효성 검사만큼만 결제하며, 월 최소 금액이나 약정은 없습니다. API 유효성 검사 호출 1회에 크레딧 1개가 들고, 캐치올 검사도 포함됩니다. 알 수 없음 결과는 자동으로 환불되며, 처음 크레딧 1,000개는 무료입니다.
모든 구간별 요금과 월 구독 할인은 요금 페이지에서 확인하십시오.
이메일 유효성 검사 API FAQ
가입 폼과 실시간 유효성 검사 구현에 관해 자주 묻는 질문입니다.
네. 새 계정은 가입 시 무료 크레딧 1,000개를 받으며, 신용카드는 필요 없습니다. 개발자 대시보드에서 API 키를 만들고 바로 실시간 폼 검사를 테스트할 수 있습니다. 무료 크레딧은 유효기간이 없고, 모든 유효성 검사 속성과 검사를 사용할 수 있습니다.
아니요. 클라이언트 측 JavaScript에서 API를 직접 호출하면, 브라우저 네트워크 요청을 살펴보는 누구에게나 비밀 API 키가 노출됩니다. 사용자 폼 입력은 먼저 자체 백엔드 서버나 서버리스 함수로 보내고, 서버에서 API(https://api.giggal.ai/v1/verify)로 요청을 보내십시오.
메시지는 전혀 발송되지 않습니다. API는 메일함이 있는지 검사하고, 이메일 데이터나 본문을 전송하기 전에 연결을 닫습니다. 사용자의 받은편지함에는 아무것도 도착하지 않습니다.
네. 모든 검사에서 도메인을 100,000개가 넘는 일회용, 임시 이메일 도메인 목록과 대조합니다. 일치하면 details.attributes.disposable 값이 true가 되고 상태가 undeliverable로 설정됩니다. 백엔드에서 이 값으로 임시 계정을 차단할 수 있습니다.
비즈니스 모델에 따라 다릅니다. 소비자용 앱에서는 support@, info@ 같은 역할 계정이 정상적인 조직일 수 있습니다. 사용자별 책임이 필요한 셀프서비스 B2B SaaS에서는 계정 공유 악용을 막기 위해 일반 역할 계정을 표시하거나 허용하지 않는 회사가 많습니다.
캐치올 도메인은 모든 수신 주소를 조건 없이 받으므로, 일반 검사로는 결론이 나지 않습니다. 이 API는 같은 호출 안에서 캐치올 심층 검증을 실행해 메일함이 있는지 평가합니다. 캐치올 검사가 “valid”를 반환하면 가입을 허용해도 안전합니다. “invalid”이면 그 주소는 반송되므로 막아야 합니다.
실패 시 허용(fail open) 방식을 권장합니다. 백엔드 호출에서 네트워크 시간 초과나 연결 오류가 생기면 잠재 고객을 막지 말고 가입을 완료하게 하십시오. 검사하지 못한 주소는 백그라운드 작업 대기열에 넣어 나중에 전송 상태를 다시 확인하십시오.
웹 가입 폼에서 제출 시점에 오타, 일회용 메일함, 봇을 막는 실시간 검사가 필요하면 이메일 유효성 검사 API를 선택하십시오. 기존 마케팅 데이터베이스를 점검하거나, CRM 연락처를 동기화하거나, 캠페인 발송 전에 대량 이메일 파일을 정리하려면 이메일 검증 API를 선택하십시오.
