ईमेल डिलीवरी का परीक्षण (मेल सैंडबॉक्स)

मेल सैंडबॉक्स किसी वास्तविक इनबॉक्स में भेजे बिना वेबहुक हैंडलर, सप्रेशन लॉजिक और डिलीवरी परिणामों का परीक्षण करता है। सामान्य API के माध्यम से messagebird.dev पर किसी पते पर भेजें। पते का स्थानीय भाग परिणाम तय करता है: bounce@messagebird.dev बाउंस होता है और delivered@messagebird.dev डिलीवर होता है।

सैंडबॉक्स में भेजा गया संदेश सामान्य स्वीकृति, इवेंट और वेबहुक पथों का उपयोग करता है। यह वही 202 प्रतिक्रिया लौटाता है और प्रत्येक प्राप्तकर्ता के लिए वही इवेंट पेलोड संरचनाएँ बनाता है जो प्रोडक्शन में भेजने पर बनती हैं। पेलोड में कोई परीक्षण फ़्लैग नहीं होता। संदेश बाहरी डिलीवरी इन्फ्रास्ट्रक्चर या किसी वास्तविक इनबॉक्स तक नहीं पहुँचता। सिम्युलेट किए गए बाउंस और शिकायतें भेजने की प्रतिष्ठा को प्रभावित नहीं करते और सप्रेशन सूची में कुछ नहीं लिखते, इसलिए आप इन पतों का दोबारा उपयोग कर सकते हैं।

सैंडबॉक्स के लिए किसी सेटअप की ज़रूरत नहीं है: न कोई टॉगल, न परीक्षण मोड, न कोई विशेष API कुंजी। यह केवल प्राप्तकर्ता के पते से सक्रिय होता है, सामान्य भेजने वाले एंडपॉइंट (POST /v1/email/messages और POST /v1/email/batches) पर और किसी ब्रॉडकास्ट पर भी। ऑडियंस में जिस संपर्क का पता सैंडबॉक्स पता है, उसे संदेश भेजा नहीं जाता बल्कि सिम्युलेट किया जाता है। इसी तरह आप किसी को मेल भेजे बिना कैंपेन का पूर्वाभ्यास करते हैं। सिम्युलेट किया गया प्राप्तकर्ता भी आपकी भेजने की सीमा में गिना जाता है, इसलिए पूर्वाभ्यास उसी कोटा का उपयोग करता है जिसका वास्तविक भेजना करता।

मैजिक पते

सभी पते @messagebird.dev पर हैं। स्थानीय भाग परिणाम चुनता है:

पता	सिम्युलेट किया गया परिणाम	वेबहुक क्रम	टिप्पणियाँ
`delivered@`	प्राप्त करने वाला मेल सर्वर संदेश स्वीकार करता है	`email.accepted` → `email.processed` → `email.delivered`	सामान्य सफल स्थिति
`bounce@` / `hardbounce@`	हार्ड बाउंस: SMTP `550`, `5.1.1 Unknown User`, बाउंस क्लास 10	`email.accepted` → `email.processed` → `email.bounced`, `bounce_type: "hard"` के साथ	सप्रेशन सूची में कुछ नहीं लिखा जाता, इसलिए पते का दोबारा उपयोग किया जा सकता है
`softbounce@`	सॉफ्ट बाउंस: SMTP `451`, `4.3.0 Temporary failure, please retry`, क्लास 20	`email.accepted` → `email.processed` → `email.bounced`, `bounce_type: "soft"` के साथ	सॉफ्ट बाउंस से कभी सप्रेशन नहीं होता, चाहे वे वास्तविक हों या सिम्युलेट किए गए
`deferred@` / `delay@`	स्थगन: SMTP `451`, `4.2.1 Mailbox temporarily unavailable, will retry`, क्लास 21	`email.accepted` → `email.processed` → `email.deferred`	सिम्युलेट किया गया स्थगन अंतिम होता है: इसके बाद कोई फिर से प्रयास नहीं होता, इसलिए प्राप्तकर्ता `deferred` ही रहता है
`complaint@` / `spam@`	प्राप्तकर्ता संदेश को स्पैम के रूप में रिपोर्ट करता है (`feedback_type: "abuse"`)	`email.accepted` → `email.processed` → `email.complained`	सप्रेशन सूची में कुछ नहीं लिखा जाता; पता दोबारा इस्तेमाल किया जा सकता है
`suppressed@`	प्राप्तकर्ता को ऐसे माना जाता है जैसे वह पहले से आपकी सप्रेशन सूची में हो	`email.accepted` → `email.rejected`, `rejection_reason: "recipient_suppressed"` के साथ	प्रोसेसिंग के दौरान ठीक किसी वास्तविक सप्रेस किए गए प्राप्तकर्ता की तरह बीच में ही रुक जाता है: न `email.processed`, न डिलीवरी इवेंट
`reject@`	डिलीवरी के किसी भी प्रयास से पहले संदेश अस्वीकार कर दिया जाता है	`email.accepted` → `email.rejected`, `rejection_reason: "transmission_failed"` के साथ	इसके बाद कोई `email.processed` या डिलीवरी इवेंट नहीं आता

ऊपर दिए गए क्रम वे वेबहुक हैं जो एक अकेला सेंड बनाता है। ब्रॉडकास्ट में शुरुआती email.accepted हटा दें: ब्रॉडकास्ट का प्राप्तकर्ता अपने आप में स्वीकार होता है, लेकिन हम उस इवेंट को दर्ज करते हैं और उसके लिए वेबहुक नहीं भेजते। इसलिए हर क्रम उसके बाद वाले इवेंट से शुरू होता है: डिलीवरी वाले रास्तों पर email.processed और suppressed@ तथा reject@ के लिए email.rejected। उसके बाद सब कुछ एक जैसा रहता है, और इवेंट संदर्भ में यह नियम पूरी तरह बताया गया है।

एक सेंड में सैंडबॉक्स और असली प्राप्तकर्ता दोनों हो सकते हैं। हर प्राप्तकर्ता का अपना जीवनचक्र होता है: असली प्राप्तकर्ताओं को संदेश सामान्य रूप से डिलीवर होता है, और सैंडबॉक्स प्राप्तकर्ताओं के लिए परिणाम सिम्युलेट किया जाता है।

यही इवेंट ईमेल लॉग में संदेश की टाइमलाइन पर और इवेंट API में भी दिखते हैं। इसलिए आप वेबहुक एंडपॉइंट के बिना भी सैंडबॉक्स चला सकते हैं और परिणाम वापस पढ़ सकते हैं।

पते के नियम

पहचान केवल लोकल पार्ट से होती है, और केवल messagebird.dev डोमेन पर। bounce@yourdomain.com एक सामान्य पता है।
केवल मैजिक पतों की तालिका में दिए गए लोकल पार्ट ही मैजिक हैं। messagebird.dev पर कोई भी अन्य पता सामान्य प्राप्तकर्ता है। जब आप साझा ऑनबोर्डिंग डोमेन से भेजते हैं, तो वह पता वर्कस्पेस के किसी सत्यापित सदस्य का होना चाहिए।
मिलान में बड़े-छोटे अक्षरों का अंतर नहीं माना जाता: Bounce@messagebird.dev और bounce@messagebird.dev एक जैसा व्यवहार करते हैं।
मिलान से पहले +label सबएड्रेसिंग हटा दी जाती है: bounce+signup-flow@messagebird.dev फिर भी बाउंस होता है। टेस्ट केस को आपस में जोड़ने के लिए लेबल का उपयोग करें। लेबल सहित पूरा पता आपके इवेंट और वेबहुक में दिखता है, इसलिए हर टेस्ट रन अपने प्राप्तकर्ताओं को टैग कर सकता है।

वॉकथ्रू: शुरू से अंत तक एक बाउंस का सिमुलेशन

आपको सत्यापित भेजने वाले डोमेन की ज़रूरत नहीं है। onboarding@messagebird.dev से भेजें, जैसा अपना पहला ईमेल भेजें में बताया गया है। पहचाने गए सैंडबॉक्स पते ऑनबोर्डिंग डोमेन की सत्यापित-सदस्य पाबंदी से मुक्त हैं, लेकिन फिर भी उसके दैनिक कोटा में गिने जाते हैं।

पक्का करें कि ईमेल इवेंट के लिए आपका कोई वेबहुक एंडपॉइंट सब्सक्राइब किया हुआ है (वेबहुक देखें), फिर भेजें:

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["bounce+signup-flow@messagebird.dev"],
  subject: "Sandbox bounce test",
  html: "<p>This message will hard-bounce.</p>",
  tags: [{ name: "flow", value: "signup" }],
  metadata: { test_run: "docs-capture-1" },
});
console.log(msg.id, msg.status); // "em_…", "accepted"

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["bounce+signup-flow@messagebird.dev"],
    subject="Sandbox bounce test",
    html="<p>This message will hard-bounce.</p>",
    tags=[{"name": "flow", "value": "signup"}],
    metadata={"test_run": "docs-capture-1"},
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
		From:     "onboarding@messagebird.dev",
		To:       []string{"bounce+signup-flow@messagebird.dev"},
		Subject:  "Sandbox bounce test",
		HTML:     "<p>This message will hard-bounce.</p>",
		Tags:     []bird.Tag{{Name: "flow", Value: "signup"}},
		Metadata: map[string]any{"test_run": "docs-capture-1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['bounce+signup-flow@messagebird.dev'],
    subject: 'Sandbox bounce test',
    html: '<p>This message will hard-bounce.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from onboarding@messagebird.dev \
  --html '<p>This message will hard-bounce.</p>' \
  --metadata '{"test_run":"docs-capture-1"}' \
  --subject 'Sandbox bounce test' \
  --tag flow=signup \
  --to bounce+signup-flow@messagebird.dev

curl -X POST "https://us1.platform.bird.com/v1/email/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["bounce+signup-flow@messagebird.dev"],
    "subject": "Sandbox bounce test",
    "html": "<p>This message will hard-bounce.</p>",
    "tags": [{ "name": "flow", "value": "signup" }],
    "metadata": { "test_run": "docs-capture-1" }
  }'

अगर आपकी कुंजी bk_eu1_ से शुरू होती है, तो इसके बजाय https://eu1.platform.bird.com को कॉल करें।

API एक em_* संदेश ID के साथ 202 Accepted लौटाता है, जो प्रोडक्शन में भेजे गए संदेश से अलग नहीं दिखता। इसी वजह से आप जिस कोड पथ का परीक्षण करते हैं, वह आपका असली कोड पथ होता है। इसके बाद आपके वेबहुक एंडपॉइंट को email.accepted, email.processed और अंत में email.bounced मिलते हैं। हर इवेंट में भेजे गए संदेश के tags और metadata लौटाए जाते हैं (अगर भेजते समय ये नहीं थे, तो null), और email.bounced पेलोड में बाउंस का पूरा वर्गीकरण होता है:

कोड उदाहरण

{
  "type": "email.bounced",
  "timestamp": "2026-07-23T14:51:00.362Z",
  "data": {
    "email_id": "em_01ky7qanhrejer0bn34v38hrxh",
    "recipient_id": "er_01ky7qanhrejds4decpk83q5qq",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "bounce+signup-flow@messagebird.dev",
    "recipient_role": "to",
    "bounce_type": "hard",
    "bounce_class": 10,
    "bounce_code": "550",
    "bounce_description": "5.1.1 Unknown User",
    "sending_ip": null,
    "tags": [{ "name": "flow", "value": "signup" }],
    "metadata": { "test_run": "docs-capture-1" },
    "broadcast_id": null
  }
}

फ़ील्ड के अर्थ इवेंट संदर्भ में दिए गए हैं। पेलोड में कहीं भी सिम्युलेटर फ़्लैग नहीं होता: इवेंट का प्रकार और ढांचा ठीक वैसा ही है जैसा असली हार्ड बाउंस से बनता है। इसे सिम्युलेटेड के रूप में पहचानने का एकमात्र आधार प्राप्तकर्ता का पता है। इसलिए अगर आपके हैंडलर को परीक्षण ट्रैफ़िक को अलग से संभालना है, तो messagebird.dev प्राप्तकर्ता डोमेन के आधार पर पहचान करें।

यह जांचने के लिए कि पहले से सप्रेस किए गए प्राप्तकर्ता को कभी कुछ नहीं भेजा जाता, suppressed@messagebird.dev के साथ फिर से भेजें। जांचें कि आपको email.accepted मिलता है, फिर rejection_reason: "recipient_suppressed" के साथ email.rejected मिलता है। आपको कोई email.processed या डिलीवरी इवेंट नहीं मिलना चाहिए। यह असली सप्रेस किए गए प्राप्तकर्ता जैसा ही व्यवहार है: संदेश स्वीकार होता है, फिर भेजे जाने से पहले प्रोसेसिंग के दौरान ही रोक दिया जाता है।

सैंडबॉक्स क्या करता है और क्या नहीं करता

सप्रेशन सूची में कुछ नहीं लिखा जाता। सिम्युलेटेड हार्ड बाउंस और शिकायतें प्राप्तकर्ता को आपकी सप्रेशन सूची में नहीं जोड़तीं; इसी कारण पते दोबारा इस्तेमाल किए जा सकते हैं। आपका वेबहुक फिर भी चलता है (email.bounced, email.complained), इसलिए आपके अपने सप्रेशन लॉजिक का पूरा परीक्षण होता है। पहले से सप्रेस किए गए प्राप्तकर्ता की अस्वीकृति वाले पथ का परीक्षण करने के लिए खास suppressed@ पते का उपयोग करें।
असली डिलीवरी कभी नहीं होती। संदेश के डिलीवरी इन्फ्रास्ट्रक्चर तक पहुंचने से पहले ही सैंडबॉक्स प्राप्तकर्ताओं को रोक लिया जाता है। कुछ भी प्रसारित नहीं होता, कोई इनबॉक्स शामिल नहीं होता और आपकी भेजने की प्रतिष्ठा पर कोई असर नहीं पड़ता।
अनुरोध की जांच फिर भी लागू होती है। सैंडबॉक्स से भेजने में सामान्य एंडपॉइंट इस्तेमाल होते हैं, इसलिए स्कीमा जांच, आकार की सीमाएं और हेडर नियम अमान्य अनुरोध को हमेशा की तरह अस्वीकार करते हैं। सैंडबॉक्स हैंडऑफ़ के बाद की हर चीज़ छोड़ देता है: उस बिंदु के बाद रेंडरिंग और डिलीवरी व्यवहार का परीक्षण नहीं होता।
ओपन और क्लिक का सिमुलेशन नहीं होता। मैजिक पता केवल ट्रांसमिशन के परिणाम का सिमुलेशन करता है और कोई संदेश नहीं खोलता, इसलिए email.opened और email.clicked केवल असली मेल से आते हैं।
आँकड़ों में सैंडबॉक्स ट्रैफ़िक शामिल होता है। सैंडबॉक्स से भेजे गए संदेश आपके वर्कस्पेस के कुल आँकड़ों और बाउंस व शिकायत दरों में गिने जाते हैं। सैंडबॉक्स में बहुत अधिक बाउंस करवाने से आपके डैशबोर्ड के आँकड़े बिगड़ जाते हैं, जबकि आपकी प्रतिष्ठा पर कोई असर नहीं पड़ता।

आगे क्या करें

इवेंट: इवेंट की पूरी शब्दावली और प्रत्येक प्राप्तकर्ता का जीवनचक्र
वेबहुक: सब्सक्राइब करना, सिग्नेचर सत्यापन और फिर से प्रयास करना
अपना पहला ईमेल भेजें: ऑनबोर्डिंग डोमेन वाली क्विकस्टार्ट गाइड, जिस पर यह वॉकथ्रू आधारित है
सप्रेशन: वास्तविक सप्रेशन सूची कैसे काम करती है
बिना किसी को स्पैम किए ईमेल टेस्ट करना: एक वीडियो, जो सैंडबॉक्स पतों और हर पते से बनने वाले इवेंट को क्रम से दिखाता है

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

अभ्यास करें और इम्प्लीमेंटेशन ब्रीफ़ पाएँ