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

मेल सैंडबॉक्स किसी असली इनबॉक्स में भेजे बिना वेबहुक हैंडलर, सप्रेशन लॉजिक और डिलीवरी परिणामों का परीक्षण करता है। सामान्य 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 सिर्फ़ असली मेल से आते हैं।
आँकड़ों में सैंडबॉक्स ट्रैफ़िक शामिल होता है। सैंडबॉक्स से भेजे गए ईमेल आपके वर्कस्पेस के कुल आँकड़ों और बाउंस व शिकायत दरों में गिने जाते हैं। सैंडबॉक्स में बहुत अधिक बाउंस कराने से आपके डैशबोर्ड के आँकड़े बिगड़ जाते हैं, जबकि आपकी प्रतिष्ठा पर कोई असर नहीं पड़ता।

आगे के चरण

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

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

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