Email, automation में एक जिद्दी dependency है। यह देर से आता है, duplicates होते रहते हैं, HTML templates बदल जाते हैं, और MIME edge cases चुपके से parsers को तोड़ देते हैं। एक temp email API infrastructure की समस्या को disposable inboxes on demand देकर हल करता है, और integration की समस्या को हर message को structured JSON के रूप में deliver करके हल करता है, ताकि आपके tests और AI agents email को data की तरह consume करें, webpage की तरह नहीं।
यह guide cover करता है कि practice में “receive and parse emails as JSON” कैसा दिखना चाहिए, webhook vs polling delivery कैसे choose करें, और OTPs व magic links को safely कैसे extract करें।
Temp email API क्या है (और इसे क्या करना चाहिए)
एक temp email API एक automation-friendly तरीका है inboxes को programmatically provision करने का, उन inboxes के लिए inbound mail receive करने का, और code से messages consume करने का।
QA और agent workflows के लिए, winning model है inbox-first:
- आप हर run या हर attempt के लिए एक fresh inbox create करते हैं।
- आपको एक routable email address मिलता है plus एक inbox handle (अक्सर एक
inbox_id)। - आप messages का deterministically wait करते हैं (webhook-first, polling fallback)।
- आप message को JSON के रूप में parse करते हैं और एक minimal artifact extract करते हैं (OTP, verification URL)।
- आप inbox को discard या rotate करते हैं।
यह आखिरी point matter करता है: short-lived inboxes cross-test collisions को reduce करते हैं और blast radius को limit करते हैं अगर कुछ leak हो जाए।
“Receive emails as JSON” का मतलब है stable contract, best-effort parse नहीं
Email RFC 5322 और MIME (RFC 2045) जैसे standards द्वारा defined है, लेकिन real-world mail अक्सर contain करता है:
- Duplicate या folded headers
- Multi-part bodies with both
text/plainऔरtext/html - Weird encodings
- Attachments और inline resources
- Threading headers जो present हैं, missing हैं, या malformed हैं
एक provider जो JSON return करता है उसे इन details को एक contract में normalize करना चाहिए जिस पर आप rely कर सकें। जब आप किसी temp email API को evaluate करते हैं, तो पूछें कि क्या JSON output इतना stable है कि आप इसके against assertions लिख सकें।
Automation और agents के लिए recommended JSON fields
एक practical JSON payload में आमतौर पर चाहिए:
| JSON field (concept) | Why it matters | Notes for reliability |
|---|---|---|
message_id (provider ID) |
Idempotency के लिए stable identifier | केवल Subject या From पर rely न करें |
received_at |
Deterministic time budgets | Client guess vs server receive time को prefer करें |
to, from
|
Routing और correlation | Address casing और formatting को normalize करें |
subject |
Debugging और loose matching | Useful, लेकिन strict matching के लिए trustworthy नहीं |
headers (normalized) |
Forensics और correlation | Duplicates और folded headers को handle करें |
text (plain) |
Safe, stable parsing target | Extraction के लिए text/plain को prefer करें |
html (optional) |
Human inspection, fallback | Untrusted input की तरह treat करें |
attachments (metadata + fetch) |
Workflows जो files email करते हैं | Attachment handling को explicit रखें |
raw (optional) |
Debugging और reprocessing | Templates change होने पर helps करता है |
अगर आप LLM tooling build कर रहे हैं, तो model के लिए एक minimized view expose करने पर consider करें (उदाहरण: from, to, subject, received_at, text, और extracted artifacts का एक छोटा set) और raw या HTML को agent context से बाहर रखें जब तक आपको वास्तव में इसकी जरूरत न हो।
Delivery patterns: webhook vs polling (और क्यों most teams को दोनों चाहिए)
Temp email API से messages receive करने के दो तरीके हैं:
Webhooks (push)
Webhooks event-driven हैं: provider आपके endpoint को call करता है जब message arrive करता है।
ये ideal हैं जब:
- आपको low latency चाहिए
- आपको fewer API calls चाहिए
- आप many parallel inboxes run करते हैं और event stream चाहते हैं
Operationally, webhooks आपको retries, signature verification, और idempotent processing के बारे में think करने की जरूरत होती है।
Polling (pull)
Polling deploy करना simpler है: आपका code repeatedly API से पूछता है कि क्या messages आए हैं।
यह useful है जब:
- आपका environment inbound web requests accept नहीं कर सकता (कुछ CI setups)
- आप पहले straightforward implementation चाहते हैं
- आपको fallback path चाहिए जब webhooks delayed या blocked हों
Polling को carefully design करना चाहिए fixed sleeps, missed messages, और duplicate processing से बचने के लिए।
Recommended hybrid
Production-grade automation में, सबसे reliable approach है:
- Fast delivery के लिए webhook-first
- Recovery के लिए polling fallback (अगर आपका webhook endpoint down था, अगर deploy हुई, या अगर notification drop हो गई)
यहाँ quick comparison है:
| Mechanism | Strength | Common pitfall | Fix |
|---|---|---|---|
| Webhook | Fast, scalable | Replay, spoofing, retries | Signatures verify करें, idempotency enforce करें |
| Polling | Simple, firewall-friendly | Rate limits, fixed sleeps, duplicates | Backoff, cursors, seen-IDs |
| Hybrid | Most robust | More moving parts | Single “wait for message” contract रखें |
Emails को JSON के रूप में safely कैसे parse करें (खासकर LLM agents के लिए)
जब provider आपको JSON देता है तब भी, email content अभी भी untrusted input है। JSON format बस consistent rules apply करना आसान बनाता है।
Deterministic extraction के लिए text/plain को prefer करें
OTP और verification flows के लिए, text/plain आमतौर पर HTML से कम बदलता है, और यह markup-related parsing failures से बचाता है।
अगर आपको HTML पर fallback करना पड़े, तो explicit safeguards के साथ करें:
- HTML को agent tool में render न करें
- Searching से पहले tags strip करें और entities decode करें
- Links को automatically “click” करने से बचें
Minimal artifacts extract करें, “meaning” नहीं
Automation के लिए आपको आमतौर पर इन artifacts में से एक चाहिए:
- एक numeric OTP
- एक verification URL (magic link)
- एक reset-password link
Goal है minimal deterministic extraction, summarization नहीं।
एक simple extraction policy:
- आपके format से match करने वाले at most one OTP candidate को accept करें
- Allowlisted domain और expected path prefix से match करने वाले at most one URL candidate को accept करें
- अगर multiple candidates हैं, तो explainable error के साथ fail करें और message IDs को log करें
Links को use करने से पहले validate करें (SSRF और open redirect hygiene)
अगर आपका automation email से URLs follow करता है, तो इसे security boundary की तरह treat करें:
- आपके control के domains को allowlist करें
- IP-literals और private network destinations को reject करें
- Unbounded redirect chains को follow न करें
OWASP SSRF Prevention Cheat Sheet link-following safety के लिए एक useful baseline है।
CI और agent workflows के लिए determinism rules
Most flaky email tests predictable reasons से fail होते हैं: shared inbox collisions, naive sleeps, और weak matching।
Inbox-per-attempt model use करें
अगर आप runs के across inboxes को reuse करते हैं, तो आप eventually wrong email पढ़ेंगे। Clean fix है: हर attempt (या कम से कम हर run) के लिए एक disposable inbox create करें और इसके inbox_id को अपने scope की तरह treat करें।
Correlation add करें जो आप control करते हैं
Matching को narrow और explainable बनाएं:
- Email trigger करने वाली action में run identifier include करें (उदाहरण: हर run के लिए unique signup email address, या metadata में correlation token जो आपका system echo करता है)
- Fuzzy subject matching से stable identifiers को JSON payload से prefer करें
Idempotency को up front design करें
Assume करें कि duplicates होंगे:
- Webhooks retry कर सकते हैं
- Polling same message को multiple times return कर सकती है
- आपका own job runner restart हो सकता है
Same logical email को once process करने के लिए inbox_id + message_id (और कभी-कभी extracted artifact hash) जैसी stable key use करें।
Scale के लिए batch processing
अगर आप बहुत सारा mail ingest करते हैं (load tests, large QA suites, या agent fleets), तो batch retrieval और processing overhead को reduce करती है और आपकी pipeline को more predictable बनाती है।
Minimal integration example (provider-agnostic pseudocode)
नीचे एक reference shape है जो QA harnesses और LLM tools दोनों के लिए अच्छी तरह काम करती है।
Inbox create करें
// Pseudocode, exact endpoints के लिए अपने provider docs देखें
const inbox = await emailApi.createInbox({
// optionally: domain strategy, webhook URL, metadata
});
// Signing up, creating users, या workflow trigger करते समय inbox.email use करें
Message का wait करें (hybrid)
async function waitForMessage({ inboxId, timeoutMs }) {
const deadline = Date.now() + timeoutMs;
// Real systems में webhook को prefer करें, लेकिन fallback के रूप में polling रखें।
// यह function एक single contract represent करता है: "first matching message return करें या time out करें"।
while (Date.now() < deadline) {
const messages = await emailApi.listMessages({ inboxId });
const candidate = pickBestCandidate(messages);
if (candidate) return candidate;
await sleep(backoffMs());
}
throw new Error(`Timed out waiting for email for inbox ${inboxId}`);
}
JSON से OTP या magic link extract करें
function extractArtifact(messageJson) {
const text = messageJson.text ?? "";
const otp = text.match(/\b\d{6}\b/)?.[0];
if (otp) return { type: "otp", value: otp };
const url = findFirstAllowlistedUrl(text, {
allowlistDomains: ["example.com"],
});
if (url) return { type: "url", value: url };
throw new Error(`No OTP or allowlisted URL found in message ${messageJson.message_id}`);
}
Important part regex नहीं है, contract है: deterministically wait करें, JSON parse करें, minimally extract करें, ambiguous होने पर loudly fail करें।
Mailhook के साथ इसे implement करना
Mailhook इसी exact automation model के around built है:
- API के via disposable inbox creation
- Emails को structured JSON के रूप में receive करें
- Real-time webhook notifications (with signed payloads)
- Fallback के लिए polling API
- Instant setup के लिए shared domains, और custom domain support
- Batch email processing
Canonical, machine-readable integration details (endpoints, payload shapes, signature verification specifics) के लिए, Mailhook का llms.txt reference use करें: Mailhook llms.txt।
आप product को Mailhook पर भी explore कर सकते हैं।
Temp email API के लिए evaluation checklist (quick sanity test)
Marketing में खो जाने के बिना providers को compare करने के लिए इसका use करें:
- क्या आप programmatically inboxes create कर सकते हैं और हर run के लिए उन्हें isolate कर सकते हैं?
- क्या messages normalized JSON के रूप में arrive करते हैं, stable IDs और timestamps के साथ?
- क्या webhooks supported हैं, और क्या payloads signed हैं?
- क्या fallback के रूप में polling available है, semantics के साथ जो duplicates से बचती है?
- क्या आप shared domains और custom domains के बीच choose कर सकते हैं?
- अगर आपको throughput चाहिए तो क्या batch processing supported है?
- क्या आप debugging के लिए raw source रख सकते हैं बिना agents को raw HTML read करने को force किए?
अक्सर पूछे जाने वाले प्रश्न
Temp email API क्या है? Temp email API आपको API के via disposable inboxes create करने, उन inboxes के लिए inbound email receive करने, और code से messages retrieve करने (अक्सर JSON के रूप में) की सुविधा देता है।
HTML scrape करने के बजाय emails को JSON के रूप में क्यों parse करना चाहिए? JSON email payload को stable और machine-readable बनाता है। HTML scraping brittle है, agents के लिए unsafe है, और templates change होने पर break हो जाती है।
Emails receive करने के लिए webhooks या polling का use करना चाहिए? Low latency और scale के लिए webhooks का use करें, और reliability के लिए polling को fallback के रूप में रखें। Hybrid “webhook-first, polling fallback” pattern सबसे robust है।
Email से OTPs या verification links को safely कैसे extract करें? text/plain को prefer करें, deterministically एक minimal artifact extract करें (one OTP या one allowlisted URL), और links को follow करने से पहले validate करें।
