किसी दूसरे प्रदाता से माइग्रेट करें

किसी दूसरे प्रदाता से प्रोडक्शन ईमेल यहाँ लाने के लिए इस गाइड का उपयोग करें। प्रोडक्शन ट्रैफ़िक को Bird पर भेजने से पहले send अनुरोध को मैप करें, DNS रिकॉर्ड प्रकाशित करें, सप्रेशन इम्पोर्ट करें, वेबहुक इवेंट का अनुवाद करें और इंटीग्रेशन का परीक्षण करें।

माइग्रेशन चेकलिस्ट:

1. अपनी भेजने की कॉल मैप करें, POST /v1/email/messages पर
2. अपने भेजने वाले डोमेन और DNS को नए सिरे से सेट करें
3. अपनी सप्रेशन सूची इम्पोर्ट करें
4. वेबहुक को हमारे इवेंट नामों पर स्विच करें
5. कटओवर से पहले मेल सैंडबॉक्स में सत्यापन करें

चरण 1, 3 और 4 इस पर निर्भर करते हैं कि आप कौन-सा प्रदाता छोड़ रहे हैं। आपकी प्रदाता गाइड में फ़ील्ड-दर-फ़ील्ड पेलोड मैपिंग, सप्रेशन सूची एक्सपोर्ट करने की जगह और वेबहुक इवेंट-नामों की अनुवाद तालिका दी गई है।

1. send कॉल को मैप करें

हमारे पास एक ही सिंगल-सेंड एंडपॉइंट है, POST /v1/email/messages। आप एक फ़्लैट JSON पेलोड बनाते हैं (कोई personalizations रैपर नहीं, कोई MIME असेंबली नहीं), जिसमें from, to/cc/bcc ऐरे, subject, html और/या text, एक वैकल्पिक reply_to सूची, और कस्टम ईमेल हेडर के लिए headers होते हैं। सफल भेजने पर 202 Accepted के साथ em_ उपसर्ग वाला मैसेज ID लौटता है। डिलीवरी के परिणाम वेबहुक और रीड एंडपॉइंट के ज़रिए एसिंक्रोनस रूप से आते हैं। हर फ़ील्ड की सीमा और डिफ़ॉल्ट के साथ पूरा पेलोड ईमेल भेजना में है। आपके मौजूदा पेलोड से फ़ील्ड-दर-फ़ील्ड मैपिंग आपकी प्रोवाइडर गाइड में है। अगर आपका ऐप्लिकेशन SMTP के ज़रिए भेजता है, तो शायद आपको कॉल पोर्ट करने की ज़रूरत ही न पड़े: हम उसी पाइपलाइन में SMTP सबमिशन स्वीकार करते हैं, जिससे यह चरण सिर्फ़ क्रेडेंशियल बदलने का काम रह जाता है।

मैसेज सूचियों, एनालिटिक्स और डैशबोर्ड सारांशों में फ़िल्टर आयामों के लिए tags का उपयोग करें। ऐसे संरचित संदर्भ के लिए metadata का उपयोग करें जिसे Bird मैसेज पर संग्रहीत करता है, API रीड पर लौटाता है और वेबहुक इवेंट में वापस भेजता है। सीमाओं के लिए टैग बनाम मेटाडेटा देखें।

कोड पोर्ट करने से पहले इन अंतरों को ध्यान में रखें:

• शेड्यूलिंग, संग्रहीत टेम्पलेट और अटैचमेंट, तीनों पोर्ट हो जाते हैं। शेड्यूल करके भेजने के लिए scheduled_at का उपयोग करें। संग्रहीत टेम्पलेट के लिए इनलाइन सामग्री की जगह template का उपयोग करें। फ़ाइलों को अटैचमेंट ऐरे में मैप करें।
• सप्रेस किए गए प्राप्तकर्ता अस्वीकार होते हैं, और यह दिखाई देता है। सप्रेस किए गए पते को भी recipient_id मिलता है, और वह मैसेज की प्राप्तकर्ता सूची में rejected स्थिति और email.rejected इवेंट (rejection_reason: recipient_suppressed) के साथ दिखता है; उसे चुपचाप हटाया नहीं जाता। सभी प्राप्तकर्ता सप्रेस किए गए हों, तब भी अनुरोध 202 के साथ स्वीकार होता है। हर प्राप्तकर्ता अस्वीकृत के रूप में लौटता है। सप्रेशन देखें।
• ऑपरेशनल मेल के लिए category: "transactional" सेट करें। डिफ़ॉल्ट रूप से भेजा गया मेल marketing होता है, और कैटेगरी सप्रेशन नीति तय करती है: marketing शिकायतों और अनसब्सक्राइब पर रुक जाता है, जबकि transactional इनके बावजूद डिलीवर होता है। न्यूज़लेटर और कैंपेन डिफ़ॉल्ट से सही तरह संभल जाते हैं। रसीदें, पासवर्ड रीसेट और इसी तरह के ऑपरेशनल मेल को transactional चिह्नित करें, ताकि अनसब्सक्राइब उन्हें न रोके।

2. डोमेन और DNS को नई जगह पॉइंट करें

हर सेंडिंग डोमेन को POST /v1/email/domains से या Email > Domains में रजिस्टर करें, फिर dns_records से मिले रिकॉर्ड प्रकाशित करें। भेजना तभी शुरू होता है जब DKIM, रिटर्न-पाथ CNAME और DMARC नीति मौजूद हों। पहले से मौजूद DMARC रिकॉर्ड, पैरेंट डोमेन वाला भी, मान्य है। ट्रैकिंग CNAME सिर्फ़ ब्रांडेड ओपन और क्लिक ट्रैकिंग के लिए ज़रूरी है। सेंडिंग डोमेन में रिकॉर्ड, सत्यापन का जीवनचक्र और क्षेत्रीय मॉडल बताए गए हैं। अगर आपका प्रोवाइडर DKIM मान को विभाजित करके मांगता है तो DNS रिकॉर्ड स्प्लिटर का, और नीति चाहिए तो DMARC नीति जनरेटर का उपयोग करें।

ज़्यादातर प्रोवाइडर जिस रिकॉर्ड से शुरुआत करवाते हैं, वह यहाँ जानबूझकर नहीं है: आप अपने डोमेन एपेक्स पर कोई SPF रिकॉर्ड प्रकाशित नहीं करते। SPF की जाँच एनवेलप-फ़्रॉम डोमेन पर होती है, जिसे रिटर्न-पाथ CNAME हमारी ओर पॉइंट करता है, इसलिए आपके एपेक्स को छुए बिना SPF पास और अलाइन हो जाता है। अगर आपके पुराने प्रोवाइडर ने आपके एपेक्स SPF रिकॉर्ड में include: जुड़वाया था, तो बदलाव के दौरान उसे रहने दें और कटओवर के बाद हटा दें। हमारे ज़रिए भेजे गए मेल पर इसका कोई असर नहीं पड़ता, और इसे हटाने से एपेक्स SPF में अनुमत 10 DNS लुकअप में से एक खाली हो जाता है। पूरा विवरण DKIM, SPF और DMARC में है।

पुराने प्रोवाइडर के रिकॉर्ड सक्रिय रहते हुए भी आप हमारे रिकॉर्ड प्रकाशित कर सकते हैं। DKIM रिकॉर्ड हमारे सेलेक्टर का उपयोग करता है। रिटर्न-पाथ और ट्रैकिंग CNAME आपके चुने हुए नए होस्टनेम हैं, और आपका मौजूदा DMARC रिकॉर्ड बिना बदलाव के शर्त पूरी करता है। ट्रैफ़िक बदलने के लिए तैयार होने तक दोनों प्रोवाइडर साथ-साथ ऑथेंटिकेट करते हैं। डोमेन की स्थिति क्षेत्रीय होती है, इसलिए जिस भी क्षेत्र से आप भेजते हैं, हर उस क्षेत्र में डोमेन रजिस्टर करें।

3. सप्रेशन इम्पोर्ट करें

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

अपने मौजूदा प्रदाता से सूची एक्सपोर्ट करें (सटीक एंडपॉइंट आपकी प्रदाता गाइड में हैं), फिर हर पते को POST /v1/email/suppressions से यहाँ जोड़ें:

while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

इस इंपोर्ट तरीके के बारे में दो बातें जानना ज़रूरी है:

• आप हर अनुरोध में एक पता इंपोर्ट करते हैं। सप्रेशन API एक-एक एंट्री वाला CRUD है, इसलिए बड़ी सूची के लिए आपको एक्सपोर्ट किए गए पतों पर लूप चलाना होगा। यह कॉल idempotent है (नए रिकॉर्ड के लिए 201, और अगर पता पहले से मैन्युअल रूप से सप्रेस किया गया है तो मौजूदा रिकॉर्ड के साथ 200), इसलिए अधूरे इंपोर्ट को दोबारा चलाना सुरक्षित है।
• इंपोर्ट किए गए पतों को reason: manual, applies_to: all मिलता है, जो ट्रांज़ैक्शनल समेत हर श्रेणी को रोकता है। यह मूल शिकायत रिकॉर्ड से ज़्यादा सख्त है, जो केवल गैर-ट्रांज़ैक्शनल भेजे जाने वाले संदेशों को रोकता है। अगर आपको कुछ खास पतों के लिए श्रेणी के अनुसार व्यवहार चाहिए, तो सप्रेशन में कारणों का वर्गीकरण देखें।

आगे से आपको बाउंस खुद संभालने की ज़रूरत नहीं है: हम हार्ड बाउंस और शिकायतों को अपने आप सप्रेस करते हैं और email_suppression.created भेजते हैं, ताकि आपके सिस्टम सप्रेशन सूची की प्रतिलिपि रख सकें। अनसब्सक्राइब को इसके बजाय एक घोषित प्राथमिकता के रूप में दर्ज किया जाता है, और उनकी प्रतिलिपि सप्रेशन इवेंट से नहीं, बल्कि email.unsubscribed और email.list_unsubscribed से बनती है।

4. वेबहुक बदलें

POST /v1/webhooks से एक एंडपॉइंट रजिस्टर करें और उसे इवेंट प्रकारों की एक स्पष्ट सूची के लिए सब्सक्राइब करें। हमारे इवेंट नाम resource.action का पालन करते हैं: सामान्य स्थिति में email.accepted → email.processed → email.delivered, और बाकी स्थितियों के लिए email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked और अनसब्सक्राइब वाली जोड़ी। आपके मौजूदा प्रदाता के इवेंट नामों का अनुवाद आपकी प्रदाता गाइड में है। हर इवेंट के पेलोड स्कीमा इवेंट संदर्भ में हैं।

सहसंबंध बिना बदलाव के पोर्ट हो जाता है। हर इवेंट में email_id, recipient_id और workspace_id पहचानकर्ता होते हैं। यह भेजने के अनुरोध से tags और metadata भी वापस लौटाता है। इससे आपको वह संदर्भ बिना किसी अतिरिक्त लुकअप के मिल जाता है, जो आपका पुराना प्रदाता पेलोड इको के ज़रिए लौटाता था। भेजते समय अपने आंतरिक ID metadata में रखें और उन्हें हर इवेंट से सीधे पढ़ें।

हम डिलीवरी पर Standard Webhooks विनिर्देश के अनुसार तीन हेडर से हस्ताक्षर करते हैं: webhook-id, webhook-timestamp और webhook-signature, जिसमें {id}.{timestamp}.{raw body} पर HMAC-SHA256 लगाया जाता है। अगर आप किसी दूसरे प्लेटफ़ॉर्म से आने वाली Standard Webhooks डिलीवरी को पहले से सत्यापित करते हैं, तो वही सत्यापन कोड यहाँ भी काम करता है। नहीं तो सत्यापन का तरीका, फिर से प्रयास का शेड्यूल और रीप्ले टूल वेबहुक और इवेंट में हैं। डिलीवरी कम से कम एक बार और बिना क्रम के होती है, इसलिए webhook-id के आधार पर डुप्लिकेट हटाएँ और पेलोड के timestamp के अनुसार क्रम लगाएँ। आपके मौजूदा हैंडलर में यह व्यवस्था पहले से होनी चाहिए।

5. कटओवर से पहले सैंडबॉक्स में सत्यापन करें

प्रोडक्शन ट्रैफ़िक ले जाने से पहले अपना पूरा इंटीग्रेशन (पोर्ट किया गया भेजने का कॉल, आपका वेबहुक हैंडलर, आपकी सप्रेशन प्रतिलिपि) मेल सैंडबॉक्स पर चलाएँ। सैंडबॉक्स से भेजे गए संदेश messagebird.dev पर मैजिक पतों पर जाते हैं और असली प्रोडक्शन पाइपलाइन से गुज़रते हैं: वही 202, वही इवेंट क्रम, वही हस्ताक्षरित वेबहुक डिलीवरी। ये संदेश कभी किसी इनबॉक्स तक नहीं पहुँचते और आपकी प्रतिष्ठा पर कोई असर नहीं डालते।

कटओवर से पहले एक न्यूनतम स्मोक टेस्ट:

1. delivered@messagebird.dev पर भेजें और जाँचें कि आपका हैंडलर email.accepted → email.processed → email.delivered को प्रोसेस करता है।
2. bounce@messagebird.dev पर भेजें और जाँचें कि email.bounced पर आपकी बाउंस हैंडलिंग चलती है (सिम्युलेटेड बाउंस आपकी सप्रेशन सूची में नहीं लिखे जाते, इसलिए पता दोबारा इस्तेमाल किया जा सकता है)।
3. suppressed@messagebird.dev पर भेजें और जाँचें कि आप email.accepted और उसके बाद email.rejected को हैंडल करते हैं, और उसके बाद कोई email.processed या डिलीवरी इवेंट नहीं आता। प्रोडक्शन में हर सप्रेस किया गया प्राप्तकर्ता यही क्रम बनाता है; rejection_reason: recipient_suppressed विवरण प्राप्तकर्ता रिकॉर्ड और इवेंट API में होता है।
4. एक category: "marketing" संदेश भेजें और पुष्टि करें कि संदेश पढ़ने पर श्रेणी वहीं दिखती है जहाँ आप उम्मीद करते हैं।

टेस्ट केस को आपस में जोड़ने के लिए +label सबएड्रेसिंग (bounce+cutover-test@messagebird.dev) का उपयोग करें। पूरा पता आपके इवेंट में दिखता है। स्मोक टेस्ट पास होने के बाद ट्रैफ़िक स्थानांतरित करें। अपने एप्लिकेशन को हमारी ओर पॉइंट करें, और जब तक यहाँ आपके डोमेन capabilities.sending सत्यापित न दिखाएँ, तब तक पुराने प्रदाता का DNS बना रहने दें। असली डिलीवरी के पहले कुछ घंटों पर डैशबोर्ड और अपनी वेबहुक स्ट्रीम में नज़र रखें।

किसी विशेष प्रदाता से माइग्रेट करना

• SparkPost: ट्रांसमिशन और SMTP, टेम्पलेट रूपांतरण, स्कोप्ड सप्रेशन और वेबहुक इवेंट
• SendGrid: personalizations → फ़्लैट पेलोड, categories/custom_args → tags/metadata, dropped ↔ email.rejected की समानता
• Mailgun: o:*/v:*/h:* पैरामीटर → प्रथम-श्रेणी फ़ील्ड, बाउंस/शिकायतें/अनसब्सक्राइब का एक्सपोर्ट
• Amazon SES: SendEmail v2 → एक एंडपॉइंट, कॉन्फ़िगरेशन सेट → प्रति-संदेश ट्रैकिंग फ़्लैग, SNS → साइन किए गए वेबहुक
• Resend: लगभग एक जैसा पेलोड ढाँचा, Svix से साइन किए गए वेबहुक → Standard Webhooks
• Postmark: अल्पविराम से अलग प्राप्तकर्ता → ऐरे, प्रति-स्ट्रीम सप्रेशन डंप, बिना साइन वाले वेबहुक → साइन किए गए
• Brevo: एड्रेस ऑब्जेक्ट → सादे पते, निर्यात करने के लिए दो अलग ब्लॉकलिस्ट, params → template.parameters
• MailerSend: पाँच सप्रेशन सूचियाँ, जिनमें से अस्थायी सूची पीछे रह जाती है, personalization → प्रति-भेजने वाले पैरामीटर
• Mailjet: Messages ऐरे → एक फ्लैट पेलोड, EventPayload → metadata, ब्लॉकलिस्ट निर्यात
• Mandrill: message रैपर और बॉडी ऑथ → फ्लैट पेलोड और बेयरर ऑथ, रिजेक्शन ब्लैकलिस्ट निर्यात

अगले चरण

• ईमेल भेजना: पूरा सेंड पेलोड, टैग बनाम मेटाडेटा, एसिंक्रोनस 202 मॉडल
• भेजने वाले डोमेन: रजिस्ट्रेशन, सत्यापन का जीवनचक्र, मल्टी-रीजन सेटअप
• DKIM, SPF और DMARC: हर रिकॉर्ड क्या साबित करता है, और एपेक्स SPF की ज़रूरत क्यों नहीं है
• सप्रेशन: कारण, श्रेणियाँ और प्रबंधन API
• वेबहुक और इवेंट: एंडपॉइंट सेटअप, Standard Webhooks सत्यापन, फिर से प्रयास और रीप्ले
• इवेंट: हर इवेंट के पेलोड स्कीमा
• टेस्टिंग सैंडबॉक्स: मैजिक पतों की पूरी सूची और चरण-दर-चरण गाइड
• API संदर्भ: भेजने वाले एंडपॉइंट के अनुरोध और प्रतिक्रिया स्कीमा