सप्रेशन

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

नया अनसब्सक्राइब कोई सप्रेशन रिकॉर्ड नहीं जोड़ता। यह डिलीवरी से जुड़े किसी तथ्य के बजाय प्राप्तकर्ता की खुद बताई गई पसंद दर्ज करता है, इसलिए यह Preferences टैब पर रहता है। यह कैसे काम करता है, जानने के लिए अनसब्सक्राइब लिंक देखें।

सूची को Email > Suppressions में, सप्रेशन API के ज़रिए, या bird email suppressions से प्रबंधित करें।

तीन कारण और वे क्या ब्लॉक करते हैं

हर रिकॉर्ड में एक reason होता है, जो बताता है कि पता सूची में क्यों है, और एक applies_to नीति होती है, जो तय करती है कि वह किन श्रेणियों को ब्लॉक करता है:

यह बँटवारा हर कारण के अर्थ से तय होता है:

• hard_bounce: पता मौजूद नहीं है। किसी भी श्रेणी में भेजने का कोई फ़ायदा नहीं, इसलिए यह सब कुछ अवरुद्ध करता है।
• complaint: यह अनचाहे मेल के बारे में एक शिकायत है। जिसने आपके न्यूज़लेटर को स्पैम बताया, उसे फिर भी पासवर्ड रीसेट या ऑर्डर की पुष्टि की ज़रूरत हो सकती है, इसलिए यह केवल गैर-लेनदेन वाले संदेश अवरुद्ध करता है।
• manual: यह आपका या आपकी टीम का सोचा-समझा फ़ैसला है। हम इस पर सवाल नहीं उठाते, इसलिए मैन्युअल सप्रेशन लेनदेन वाली श्रेणी सहित हर श्रेणी को अवरुद्ध करता है।

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

नोट: सप्रेशन API पर reason: unsubscribe अप्रचलित है। नए अनसब्सक्राइब सप्रेशन के बजाय एक पसंद दर्ज करते हैं। अप्रचलित ?reason=unsubscribe फ़िल्टर तब तक origin: unsubscribe_link या origin: unsubscribe_event वाले पुराने सप्रेशन रिकॉर्ड लौटाता रहता है, जब तक वे रिकॉर्ड हटाए नहीं जाते।

पते अपने-आप कैसे जुड़ते हैं

हम प्राप्तकर्ता से मिले संकेतों के आधार पर सप्रेशन जोड़ते हैं, इसलिए बाउंस या शिकायत होने पर आपको कुछ नहीं करना पड़ता:

अनसब्सक्राइब यहाँ नहीं दिखता, चाहे वह ईमेल के भीतर दिए गए लिंक से हो या वन-क्लिक बटन से: वह इस सूची में कोई पंक्ति जोड़ने के बजाय Preferences टैब पर एक प्राथमिकता दर्ज करता है।

केवल hard वर्ग का बाउंस ही सप्रेशन बनाता है, और वर्गीकरण तालिका बताती है कि कौन-से bounce_class मान हार्ड माने जाते हैं। विफलता जैसे दिखने वाले दो परिणामों के बाद भी पते पर भेजा जा सकता है:

• सॉफ़्ट बाउंस और डेफ़रल (email.deferred, या bounce_type: "soft" के साथ email.bounced): भरा हुआ मेलबॉक्स जैसी अस्थायी विफलताएँ। हम फिर से प्रयास करते हैं।
• भेजने की ओर से अस्वीकृतियाँ: जनरेशन विफलताएँ और नीति के कारण अस्वीकृतियाँ पते की नहीं, बल्कि भेजे गए संदेश की समस्याएँ हैं। इनसे email.rejected इवेंट बनते हैं, कोई सप्रेशन नहीं।

जो पता पहले से उसी कारण से सप्रेस किया गया है, उसके लिए दोबारा आने वाले संकेत मूल रिकॉर्ड को नहीं बदलते, उसके created_at को भी नहीं। रिकॉर्ड में source_email_id और source_recipient_id बने रहते हैं, जो किसी स्वचालित सप्रेशन को उसी संदेश और प्राप्तकर्ता से जोड़ते हैं जिसके कारण वह बना। ये दोनों फ़ील्ड सपोर्ट के सवाल "why did this person stop getting our email" का उत्तर देते हैं, और मैन्युअल रूप से जोड़े गए रिकॉर्ड में ये null होते हैं।

हर नया रिकॉर्ड, चाहे स्वचालित हो या मैन्युअल, आपके वेबहुक एंडपॉइंट पर एक email_suppression.created इवेंट भेजता है। इसमें suppression_id, सप्रेस किया गया email, reason और workspace_id होते हैं, ताकि आपका सिस्टम बार-बार जाँच किए बिना सूची की प्रति रख सके:

{
  "type": "email_suppression.created",
  "timestamp": "2026-07-23T14:52:03.192524705Z",
  "data": {
    "email": "user@example.com",
    "reason": "manual",
    "suppression_id": "sup_01ky7qckqrf06r38g49b9kxdbc",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
  }
}

API के ज़रिए सप्रेशन प्रबंधित करना

API एक-एक रिकॉर्ड जोड़ता, सूचीबद्ध करता, खोजता और हटाता है। पतों को संग्रहीत करने और खोजने से पहले लोअरकेस में बदला जाता है, और वे कभी URL पाथ में नहीं आते, क्योंकि पाथ एक्सेस लॉग में दर्ज होता है और ईमेल पता व्यक्तिगत डेटा है। किसी पते का रिकॉर्ड ढूँढने के लिए सूची को ?email= से फ़िल्टर करें।

हर SDK इन ऑपरेशनों को अपने suppressions रिसोर्स पर टाइप किए गए मेथड के रूप में उपलब्ध कराता है।

पता जोड़ें

const suppression = await bird.suppressions.add({ email: "user@example.com" });
console.log(suppression.id);

suppression = client.suppressions.add(email="user@example.com")
print(suppression.id)

suppression, err := client.Suppressions.Add(context.Background(), bird.SuppressionsAddParams{
	Email: "user@example.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(suppression.Id)

$suppression = $bird->suppressions->add(
    (new SuppressionCreate())->setEmail('user@example.com'),
);
echo $suppression->getId();

bird email suppressions add --email user@example.com

curl -X POST https://us1.platform.bird.com/v1/email/suppressions \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

मैन्युअल रूप से जोड़े गए पतों को reason: manual और applies_to: all मिलते हैं, इसलिए वे हर श्रेणी को अवरुद्ध करते हैं। यह कॉल आइडेम्पोटेंट है: नया सप्रेशन 201 Created लौटाता है, और जो पता पहले से मैन्युअल रूप से सप्रेस किया गया है, उसके लिए कॉन्फ़्लिक्ट के बजाय मौजूदा रिकॉर्ड के साथ 200 OK लौटता है। दोनों स्थितियों में बॉडी सप्रेशन ऑब्जेक्ट होती है:

{
  "applies_to": "all",
  "created_at": "2026-07-23T14:52:03.192524705Z",
  "email": "user@example.com",
  "id": "sup_01ky7qckqrf06r38g49b9kxdbc",
  "origin": "api_key",
  "reason": "manual",
  "scope": {
    "id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "type": "workspace"
  }
}

origin फ़ील्ड बताता है कि रिकॉर्ड कैसे बना। मैन्युअल रूप से जोड़े गए रिकॉर्ड को api_key या user मिलता है, यह इस पर निर्भर करता है कि कॉलर ने API कुंजी से प्रमाणीकरण किया या डैशबोर्ड सेशन से। अपने-आप जोड़े गए रिकॉर्ड को bounce_event या complaint_event मिलता है, यह इस पर निर्भर करता है कि उन्हें किस संकेत ने बनाया।

सूची देखें और खोजें

ये कॉल पहला पेज लौटाती हैं। Go में खाली तीसरा आर्ग्युमेंट पेजिनेशन शुरू करता है; अगला पेज पढ़ने के लिए पिछले पेज का NextCursor पास करें।

const page = await bird.suppressions.list({ limit: 25 });
console.log(page.data.length);

page = client.suppressions.list(limit=25)
print(len(page.data))

page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{Limit: 25}, "")
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(page.Data))

$page = $bird->suppressions->list(['limit' => 25])->fetch();
echo count($page->data);

bird email suppressions list --limit 25

curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
  -H "Authorization: Bearer $BIRD_API_KEY"

सूची कर्सर से पेजिनेट होती है, सबसे नए रिकॉर्ड पहले आते हैं, और इसे reason से फ़िल्टर किया जा सकता है। किसी एक पते की जाँच के लिए उसे email क्वेरी पैरामीटर के रूप में पास करें:

const page = await bird.suppressions.list({ email: "user@example.com" });
console.log(page.data.length);

page = client.suppressions.list(email="user@example.com")
print(len(page.data))

page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{
	Email: "user@example.com",
}, "")
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(page.Data))

$page = $bird->suppressions->list(['email' => 'user@example.com'])->fetch();
echo count($page->data);

bird email suppressions list --email user@example.com

curl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
  -H "Authorization: Bearer $BIRD_API_KEY"

email फ़िल्टर केस का ध्यान रखे बिना प्रीफ़िक्स से मिलान करता है: user@example.com से user@example.com.au भी मेल खाता है। लौटे हर पते की तुलना उस पूरे पते से करें जिसका आपने अनुरोध किया था, और मेल खाता रिकॉर्ड मौजूद है या नहीं, यह तय करने से पहले हर पेज पर next_cursor का पालन करें। एक पते पर कई रिकॉर्ड लागू हो सकते हैं। MCP कॉलर सटीक पते की इस खोज के लिए email_suppressions_check का उपयोग कर सकते हैं।

सप्रेशन ID मिलने के बाद GET /v1/email/suppressions/{suppression_id} वही एक रिकॉर्ड लौटाता है: SDK में suppressions.get, या CLI पर bird email suppressions get <id>।

पता हटाएँ

await bird.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc");

client.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc")

if err := client.Suppressions.Remove(context.Background(), "sup_01ky7qckqrf06r38g49b9kxdbc"); err != nil {
	log.Fatal(err)
}

$bird->suppressions->remove('sup_01ky7qckqrf06r38g49b9kxdbc');

bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yes

curl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
  -H "Authorization: Bearer $BIRD_API_KEY"

एक कारण वाले रिकॉर्ड इस तरह नहीं हटाए जा सकते। complaint रिकॉर्ड केवल साइन-इन किया हुआ डैशबोर्ड उपयोगकर्ता हटा सकता है; API कुंजी को 422 SuppressionNotRemovableByAPIKey मिलता है। hard_bounce और manual रिकॉर्ड दोनों तरीकों से हटाए जा सकते हैं।

यह 204 No Content लौटाता है और उस रिकॉर्ड को स्थायी रूप से हटा देता है। उसी पते के दूसरे रिकॉर्ड बने रहते हैं, और जब तक कोई बचा हुआ रिकॉर्ड संदेश की श्रेणी को अवरुद्ध करता है, डिलीवरी अवरुद्ध रहती है। पते के आधार पर रिकॉर्ड हटाने के लिए ?email= खोज के सभी पेज देखें, केवल पूरे पते से मेल खाने वाले रिकॉर्ड चुनें, और हर इच्छित रिकॉर्ड को ID से हटाएँ। hard_bounce रिकॉर्ड सोच-समझकर हटाएँ, क्योंकि जो पता अब भी मौजूद नहीं है, वह अगली बार भेजने पर बाउंस होता है और खुद फिर से सप्रेस हो जाता है।

सप्रेस किए गए पते पर भेजने पर क्या होता है

हम प्राप्तकर्ता को ऐसी जगह अस्वीकार करते हैं जहाँ आप उसे देख सकें। प्राप्तकर्ता को recipient_id मिलता है और वह संदेश की प्राप्तकर्ता सूची में rejected स्थिति के साथ दिखता है। इवेंट API और आपके वेबहुक rejection_reason: "recipient_suppressed" के साथ एक email.rejected इवेंट दर्ज करते हैं। बाकी प्राप्तकर्ताओं को डिलीवरी सामान्य रूप से होती है।

संदेश स्वयं फिर भी 202 के साथ स्वीकार किया जाता है, भले ही उसके सभी प्राप्तकर्ता सप्रेस किए गए हों। हम भेजने का अनुरोध स्वीकार करने के बाद, संदेश को प्रोसेस करते समय सप्रेशन की जाँच करते हैं। इसलिए अभी जोड़ा गया पता कुछ मिनटों में लागू हो जाता है और पहले से चल रहे भेजने के काम को कभी नहीं रोकता।

सैंडबॉक्स से परीक्षण

परीक्षण सैंडबॉक्स सप्रेशन के व्यवहार को निश्चित परिणामों के साथ जाँचता है। suppressed@messagebird.dev पर भेजना ऐसा व्यवहार करता है मानो पता आपकी सूची में हो: प्राप्तकर्ता rejection_reason: "recipient_suppressed" के साथ अस्वीकार होता है और डिलीवरी तक कभी नहीं पहुँचता। सैंडबॉक्स के बाउंस और शिकायत वाले पते (bounce@messagebird.dev, complaint@messagebird.dev) अपने परिणाम असली इवेंट पाइपलाइन से गुज़ारते हैं, लेकिन आपकी सप्रेशन सूची में कुछ नहीं लिखते। इसलिए वही परीक्षण पते हर रन में दोबारा इस्तेमाल किए जा सकते हैं।

अगले कदम

• श्रेणियाँ: transactional और marketing में अंतर, और श्रेणी सप्रेशन नीति के साथ कैसे काम करती है
• अनसब्सक्राइब लिंक: ऑप्ट-आउट सप्रेशन के बजाय बताई गई पसंद को कैसे दर्ज करते हैं
• इवेंट और वेबहुक: email.rejected पेलोड और वे लाइफ़साइकल इवेंट जिनसे स्वचालित सप्रेशन होता है
• परीक्षण सैंडबॉक्स: हर डिलीवरी परिणाम का अनुकरण करने वाले विशेष पते
• API संदर्भ: सप्रेशन: अनुरोध और प्रतिक्रिया के पूरे स्कीमा
• जब कोई ऑप्ट आउट करता है तो क्या होता है: एक वीडियो जो एक प्राप्तकर्ता को अनसब्सक्राइब पेज से अस्वीकार किए गए संदेश तक दिखाता है