API इंस्टेंट इनबॉक्स: बनाएं, उपयोग करें और सुरक्षित रूप से समाप्त करें

जब आपके वर्कफ़्लो को अभी तुरंत एक ईमेल पते की जरूरत होती है, तो human mailbox की प्रतीक्षा करना या shared test inbox का पुन: उपयोग करना flaky tests, leaked secrets, और भ्रमित करने वाले “यह कौन सा run था?” debugging का सबसे तेज़ रास्ता है।

एक API के द्वारा इंस्टेंट इनबॉक्स इस model को उलट देता है। आप एक single purpose (एक test run, एक verification attempt, एक agent task) के लिए एक fresh, disposable inbox प्रावधान करते हैं, incoming email को structured JSON के रूप में consume करते हैं, और फिर inbox को एक short, intentional lifecycle पर expire होने देते हैं।

यह गाइड create, use, और expire करने का एक practical, reliability-first तरीका दिखाता है जो CI, QA automation, और LLM agents के लिए अच्छी तरह काम करता है।

Canonical Mailhook API contract और exact request/response shapes के लिए, उपयोग करें: mailhook.co/llms.txt

“Instant inbox” का मतलब क्या होना चाहिए (“एक random email address” से कहीं अधिक)

Automation और agents के लिए, एक instant inbox केवल एक syntactically valid address नहीं है। यह एक routable email destination है जिसमें एक handle है जिसे आप query कर सकते हैं, clear lifecycle semantics, और deterministic delivery mechanics हैं।

यहाँ वे properties हैं जो practice में matter करती हैं:

Provisionable: REST API के द्वारा on demand inboxes बनाएं।
Isolated: प्रति run, attempt, या agent task एक inbox, ताकि parallelism safe हो।
Machine-readable: प्राप्त emails को structured JSON के रूप में deliver किया जाता है, ताकि आप fields पर assert कर सकें, brittle HTML पर नहीं।
Eventable: low-latency notification (webhooks) plus एक deterministic fallback (polling) reliability के लिए।
Expirable: एक clear TTL ताकि inboxes accidental data stores न बन जाएं।
Authenticable: webhook payloads verifiable होने चाहिए (Mailhook signed payloads को support करता है)।

अगर आपका “instant inbox” provider lifecycle और authenticity को model नहीं कर सकता, तो आप उन guarantees को एक unreliable primitive के ऊपर rebuild कर रहे होते हैं।

Lifecycle: create, receive, extract, expire

एक instant inbox के बारे में सोचने का एक simple तरीका यह है कि इसे एक short-lived resource के रूप में देखा जाए जिसका एक contract है।

चार boxes के साथ एक simple lifecycle diagram जो बाएं से दाएं connected हैं: Create Inbox (API) -> Use Address (signup या trigger email) -> Receive Email (webhook या polling, JSON) -> Expire and Cleanup (TTL, retention). हर box में एक small icon है (plus, envelope, webhook hook, trash/clock).

यहाँ lifecycle को phases में broken down किया गया है जिन्हें आप code के रूप में implement कर सकते हैं:

Phase	आप क्या करते हैं	आपको क्या store करना चाहिए	क्या गलत हो सकता है
Create	API के द्वारा एक new inbox resource provision करें	`inbox_id`, `email`, `expires_at` (या equivalent)	Inboxes का reuse, no TTL, runs में collisions
Use	Email address को system under test या agent task में feed करें	Correlation metadata (run/attempt IDs)	Wrong address, wrong environment domain
Receive	Webhook (preferred) या polling (fallback) के द्वारा arrival का wait करें	Delivery IDs, message IDs, minimal derived artifact	Duplicate deliveries, spoofed webhooks, fixed sleeps
Extract	Minimal artifact (OTP, magic link) को deterministically extract करें	Artifact hash, extracted value, timestamps	HTML scraping breaks, agent में prompt injection
Expire	Inbox को expire होने दें और new work को accept करना बंद करें	Audit logs (केवल IDs), deletion markers	Retention creep, accidental PII capture

Step 1: API के द्वारा एक instant inbox बनाएं

सबसे robust pattern एक inbox बनाना और एक ऐसा object pass around करना है जिसमें दोनों शामिल हों:

email address (जो external system को चाहिए), और
एक inbox handle (जो आपका code messages को deterministically retrieve करने के लिए use करता है)।

कई teams इस pattern को “email plus inbox handle” कहते हैं। यह आपके automation को shared mailbox scan करने से रोकता है, और यह parallel runs को safe बनाता है।

एक typical create response conceptually इस तरह दिखता है:

{
  "email": "unique-key@your-inbox-domain",
  "inbox_id": "inbox_...",
  "expires_at": "2026-02-27T22:10:45Z"
}

Field names provider के अनुसार अलग होते हैं, इसलिए इसे एक shape के रूप में treat करें, promise के रूप में नहीं। Mailhook के exact contract के लिए, llms.txt refer करें।

Shared domain vs custom domain

आपकी domain choice deliverability और governance को प्रभावित करती है:

Shared domains start करने के लिए fastest हैं (कोई DNS work नहीं) और early CI और prototyping के लिए बेहतरीन हैं।
Custom domain support valuable है जब आपको allowlisting, stronger environment isolation, या tighter operational control की जरूरत है।

Mailhook दोनों shared domains और custom domains को support करता है, ताकि आप simple start कर सकें और जब आपकी constraints change हों तो upgrade कर सकें।

Step 2: Correlation built in के साथ address का use करें

Instant inboxes अपनी power correlation से पाते हैं। Inbox पहले से ही isolated है, लेकिन आप अभी भी logs और retries में traceability चाहते हैं।

एक practical approach:

हर workflow के लिए एक run_id या attempt_id generate करें।
उस ID को अपने internal logs में डालें।
अगर आप sending system को control करते हैं, तो इसे header या template variable में include करें (उदाहरण के लिए, एक internal reference string के रूप में), फिर उस पर match करें।

यह debugging को actionable रखता है: जब एक run fail हो जाता है, तो आप “कौन सा inbox, कौन सा message, कौन सी delivery?” का जवाब जल्दी दे सकते हैं।

Step 3: Emails को deterministically receive करें (webhook first, polling fallback)

Webhook-first: instant workflows के लिए default

Webhooks instant inbox flows के लिए best default हैं क्योंकि ये low latency और parallel-safe हैं। आपका handler retries और duplicates को tolerate करने के लिए designed होना चाहिए।

Key practices:

Authenticity verify करें: अगर आपका provider signed payloads support करता है, तो parsing से पहले उन्हें verify करें।
Processing को idempotent बनाएं: एक delivery identifier (या एक stable message identifier) store करें और repeats को ignore करें।
Quickly acknowledge करें: webhook handler में minimal work करें, deeper processing को elsewhere enqueue करें।

Conceptual webhook verification flow:

receive webhook -> verify signature over raw body -> check timestamp tolerance -> dedupe -> enqueue -> respond 2xx

Mailhook security के लिए signed payloads को support करता है, जो agent workflows के लिए बहुत बड़ी बात है जहाँ spoofing और replay real threats हैं।

Polling fallback: “still succeeds” path

Webhooks के बाद भी, आपको polling fallback चाहिए:

temporary webhook downtime के लिए,
local development के लिए,
CI environments के लिए जहाँ inbound HTTP constrained है।

एक deterministic polling loop को चाहिए:

deadline के साथ poll करना (fixed sleep नहीं),
reprocessing से बचने के लिए “seen” cursor रखना,
inbox expire होने पर stop करना।

Conceptual polling pseudocode:

const deadline = Date.now() + 60_000;
let cursor = null;

while (Date.now() < deadline) {
  const messages = await listMessages({ inbox_id, cursor });

  const match = findMatch(messages, {
    subjectContains: "Your verification code",
    toEquals: email
  });

  if (match) return match;

  cursor = nextCursor(messages);
  await sleep(500);
}

throw new Error("Timed out waiting for email");

यह style CI में stable है: आप budget के अंदर एक matching message प्राप्त करते हैं, या आप एक clear timeout के साथ fail हो जाते हैं जिसमें run_id और inbox_id शामिल है।

Step 4: केवल वही extract करें जिसकी आपको जरूरत है (विशेष रूप से LLM agents के लिए)

Tests और agent tasks के लिए, आपको शायद ही कभी “email को human की तरह read” करने की जरूरत होती है। आपको एक artifact चाहिए:

OTP code
magic link
verification URL
reset link

Email को untrusted input के रूप में treat करें। Emails में trackers, unexpected HTML, और ऐसा content हो सकता है जो downstream systems को manipulate करने की कोशिश करता है।

Recommended guardrails:

HTML render करने के बजाय JSON output से text-like fields को prefer करें।
Strict bounds के साथ narrow parser (regex या URL parser) के द्वारा extract करें।
किसी भी fetch से पहले outbound URLs को validate करें।

LLM-agent specific safety notes

अगर एक LLM agent email content देखेगा, तो interface को constrain करके risk reduce करें:

Agent को full message नहीं, केवल minimal extracted artifact provide करें।
अगर आपको message content provide करना ही है, तो minimized JSON view (केवल selected fields) provide करें और length को cap करें।
Agent को बिना allowlists के blindly links follow करने की अनुमति न दें।

यह न केवल एक security measure है, बल्कि ambiguity reduce करके agent reliability को भी improve करता है।

Step 5: Safely expire करें (TTL, drain windows, और retention discipline)

अधिकांश teams “create” part को सही करते हैं और “expire” part को गलत।

एक safe expiry strategy तीन सवालों के जवाब देती है:

New messages के लिए inbox कितनी देर valid है? (TTL)
Debugging के लिए आप messages को कितनी देर available रखते हैं? (retention)
Expiry के बाद क्या होता है? (hard delete, tombstone, या access denied)

भले ही provider inbox को automatically expire कर देता हो, आपको अभी भी expiry को अपने integration का first-class part treat करना चाहिए।

Practical TTL recommendations

Default में short TTLs use करें, फिर केवल उन workflows के लिए increase करें जिन्हें वास्तव में इसकी जरूरत है।

Use case	Suggested TTL	क्यों
Signup verification test (CI)	10 से 30 minutes	Retries और queue delays के लिए enough, retention creep को limit करता है
Password reset test	15 से 45 minutes	Reset emails slower हो सकते हैं और कभी-कभी retried हो सकते हैं
LLM agent “wait for email” tool	5 से 20 minutes	Agent tasks को bounded रखता है और leak risk reduce करता है
Manual QA debugging session	1 से 4 hours	Humans slower हैं, लेकिन फिर भी इसे temporary रखें

Expiry checklist

Inbox expire होने पर polling stop करें।
CI logs में message bodies को redact करें या log करने से बचें।
Troubleshooting के लिए जरूरी identifiers (inbox ID, message ID, timestamps) को store करें।
अगर आप debugging के लिए message JSON persist करते हैं, तो retention policy और access controls apply करें।

अगर आप regulated environments के लिए build कर रहे हैं, तो inboxes को sensitive resources के रूप में treat करने पर विचार करें भले ही वे “disposable” हों।

Reliability patterns जो flaky tests को prevent करते हैं

Instant inboxes email flakiness की एक huge class को remove करते हैं, लेकिन केवल तभी जब आप consumption contract को tight रखते हैं।

Common pitfalls और fixes:

Pitfall	Symptom	Fix
Fixed sleeps	CI में random timeouts	Deadline-based wait (webhook या polling)
Shared inbox reuse	Tests wrong message पर assert करते हैं	प्रति run या प्रति attempt एक inbox
Wide matchers	“Found an email” लेकिन यह wrong है	Narrow match: recipient + subject intent + time window
No dedupe	OTP या link की double-processing	Idempotency keys store और enforce करें
No webhook verification	Spoofing और replay risk	Signed payloads verify करें और failures को reject करें

Mailhook की primitives इन needs पर cleanly map करती हैं: API के द्वारा disposable inbox creation, real-time webhook notifications, fallback के लिए polling, और authenticity के लिए signed payloads।

Batching और high-throughput runs के लिए implementation notes

अगर आप large suites या many agent tasks चलाते हैं, तो आप throughput के बारे में care करेंगे।

दो practical considerations:

Batch email processing: backfills, reprocessing, या large parallel runs करते समय messages को batches में consume करना prefer करें।
Backpressure: webhook handlers को fast रखें, work को queue करें, और asynchronously process करें।

यह आपकी inbound email layer को आपकी CI की bottleneck बनने से रोकता है।

FAQ

Instant inbox क्या है? Instant inbox एक disposable, programmatically created inbox है जो real emails receive कर सकता है और उन्हें आपके code को (अक्सर JSON के रूप में) clear lifecycle और retrieval semantics के साथ deliver कर सकता है।

मैं signup verification के लिए instant inbox का safely कैसे उपयोग करूं? प्रति attempt एक fresh inbox बनाएं, email को quickly receive करने के लिए webhooks use करें, signed payloads verify करें, केवल OTP या verification link extract करें, फिर inbox को expire होने दें।

Webhooks या polling, कौन सा बेहतर है? Webhooks आमतौर पर latency और scale के लिए बेहतर हैं। Polling अभी भी valuable है fallback के रूप में जब webhooks temporarily unavailable हों या inbound HTTP constrained हो।

एक disposable inbox कितनी देर जीना चाहिए? CI और agent workflows के लिए, TTLs को short रखें (अक्सर minutes, days नहीं)। Long-lived inboxes shared state बन जाते हैं और leaks और collisions की chance बढ़ाते हैं।

क्या LLM agents emails को directly read कर सकते हैं? वे कर सकते हैं, लेकिन agents को केवल minimal extracted artifact (OTP या URL) देना safer है और email content को untrusted input treat करना।

Instant inbox workflows के लिए Mailhook try करें

अगर आपको automation और agents के लिए built एक instant inbox via API चाहिए, तो Mailhook disposable inbox creation, structured JSON के रूप में delivered emails, real-time webhooks, polling fallback, signed payloads, और batch processing provide करता है।

यहाँ start करें: Mailhook
Canonical API contract यहाँ use करें: mailhook.co/llms.txt

Get started करने के लिए कोई credit card की जरूरत नहीं है।

API के द्वारा इंस्टेंट इनबॉक्स: सुरक्षित रूप से बनाएं, उपयोग करें और समाप्त करें