Sign inGet Started

शेड्यूल्ड सेंडिंग

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

सेंड शेड्यूल करना

एक सामान्य POST /v1/email/messages सेंड में scheduled_at टाइमस्टैम्प जोड़ें। पेलोड में और कुछ नहीं बदलता।
const msg = await bird.email.send({
  from: "news@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your weekly digest",
  html: '<p>Here is what happened this week...</p><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></p>',
  category: "marketing",
  scheduled_at: "2027-01-15T09:00:00Z",
});
console.log(msg.id, msg.status); // "em_…", "accepted"
कॉल तुरंत em_-प्रीफ़िक्स्ड मैसेज ID और status: accepted के साथ 202 Accepted लौटाता है। यह वही मैसेज ऑब्जेक्ट है जो तत्काल सेंड लौटाता है, साथ में scheduled_at UTC में वापस दिया जाता है, ताकि आप बिना अलग से रीड किए भेजने का समय पुष्टि कर सकें। स्वीकृति सिंक्रोनस है; डिलीवरी डिफ़र्ड है। रिक्वेस्ट से scheduled_at हटा दें तो संदेश तुरंत भेज दिया जाता है, और उसके रिस्पॉन्स में कोई scheduled_at key नहीं होती।
पढ़ने पर मिलने वाली जानकारी असिंक्रोनस रूप से अपडेट होती है। आपने अभी जो संदेश शेड्यूल किया है, उसके लिए संदेश प्राप्त करें शुरू में 404 लौटा सकता है, और हो सकता है कि संदेश सूची या डैशबोर्ड में वह संदेश अभी दिखाई न दे। बड़ी सामग्री या अटैचमेंट को सहेजने के दौरान यह इंतज़ार बढ़ सकता है। 202 प्रतिक्रिया से ID और scheduled_at सहेजकर रखें। उसी ID से पढ़ने के अनुरोध फिर से करें और प्रयासों के बीच अंतराल रखें। संदेश दिखाई देने से पहले भी आप इसी ID से उसे रद्द कर सकते हैं।
जब कोई संदेश दिखाई देता है और अभी भेजे जाने का इंतज़ार कर रहा होता है, तो पढ़ने पर status: scheduled और उसका scheduled_at दिखता है:
कोड उदाहरण
{
  "id": "em_01ky7q24hafjgvzfg02v3m177p",
  "status": "scheduled",
  "scheduled_at": "2027-01-15T09:00:00Z",
  "category": "marketing"
}
जब समय आता है, हम संदेश रिलीज़ करते हैं और उसकी स्थिति सामान्य स्टेट्स से गुज़रती है (accepted, फिर processed, फिर delivered, इत्यादि)। scheduled_at बाद में भी सेट रहता है, ताकि आप हमेशा देख सकें कि संदेश किस समय के लिए शेड्यूल किया गया था।
पढ़ने पर मिलने वाली जानकारी अपडेट होने से पहले संदेश भेजना शुरू हो सकता है, इसलिए आपको सबसे पहले बाद की कोई स्थिति दिख सकती है। कोई तय अवधि नहीं है जिसके बाद पढ़ने पर संदेश दिखने की गारंटी हो।
शेड्यूलिंग बिलिंग अवधि के लिए आपके संगठन के शेड्यूल्ड-ईमेल कोटे की एक यूनिट खर्च करती है। उस कोटे से अधिक होने पर 422 (E10003) के साथ अस्वीकार कर दिया जाता है।

इनलाइन सामग्री या टेम्पलेट से भेजने का समय तय करें

इनलाइन सामग्री या सहेजे गए टेम्पलेट के साथ scheduled_at का इस्तेमाल करें, जिसे तत्काल टेम्पलेट सेंड की तरह ही बनाया जाता है। हम अनुरोध स्वीकार करते समय प्रकाशित संस्करण, चुनी गई भाषा और पैरामीटर के मान तय कर देते हैं और निर्धारित समय पर उसी संस्करण को भेजते हैं। नया संस्करण प्रकाशित करने से यह चयन नहीं बदलता। निर्धारित समय से पहले टेम्पलेट हटाने पर संदेश बिना भेजे रिजेक्ट हो जाता है।
marketing श्रेणी के संदेश की बॉडी के अंत में एक छोटे फ़ुटर के रूप में सदस्यता समाप्त करने का लिंक जुड़ जाता है। लिंक की जगह खुद तय करने के लिए, दी गई हर बॉडी में {{ bird.unsubscribe_url }} रखें, या टेम्पलेट सेंड के लिए टेम्पलेट की बॉडी में।
एक बैच आइटम उन्हीं शर्तों पर scheduled_at लेता है, इसलिए एक बैच में शेड्यूल्ड और तत्काल संदेश मिला सकते हैं। हर शेड्यूल्ड आइटम कोटे की अपनी अलग यूनिट लेता है, और अगर किसी भी आइटम का समय सीमा से बाहर है तो पूरा बैच अस्वीकार कर दिया जाता है। हर शेड्यूल्ड आइटम बैच रिस्पॉन्स में अपना scheduled_at वापस लेकर आता है, और तुरंत भेजे गए आइटम में कोई scheduled_at key नहीं होती; बैच रेफ़रेंस दोनों को एक रिस्पॉन्स में दिखाता है।
तत्काल-सेंड पेलोड शेड्यूल करने के लिए बहुत बड़ा भी हो सकता है। अगर उसकी बॉडी, प्राप्तकर्ता सूची, या मेटाडेटा शेड्यूलिंग सीमा से अधिक है, तो API 422 लौटाता है। उन फ़ील्ड्स को कम करें या संदेश तुरंत भेजें।

भेजने का समय चुनना

scheduled_at एक एब्सोल्यूट RFC 3339 टाइमस्टैम्प है। इसे दो नियम नियंत्रित करते हैं:
  • यह भविष्य में 30 सेकंड से 30 दिन के बीच होना चाहिए। 30 सेकंड से कम या 30 दिन से अधिक होने पर 422 के साथ अस्वीकार कर दिया जाता है। निचली सीमा शेड्यूल को तत्काल सेंड से प्रतिस्पर्धा करने से रोकती है। तीस दिन वह अधिकतम अवधि है जब तक हम कोई संदेश रोककर रखते हैं।
  • एक सटीक क्षण दें। UTC Z (2027-01-15T09:00:00Z) या एक स्पष्ट ऑफ़सेट (2026-07-30T09:00:00-04:00, जो 13:00:00Z के समान ही क्षण है) शामिल करें। हम उस क्षण की तुलना वर्तमान समय से करते हैं और कभी भी किसी बेयर लोकल टाइम की व्याख्या नहीं करते या प्राप्तकर्ता का टाइमज़ोन लागू नहीं करते। हर प्राप्तकर्ता के स्थानीय समय सुबह 9 बजे भेजने के लिए, वे क्षण स्वयं निकालें और प्रति टाइमज़ोन एक सेंड शेड्यूल करें।
"in 2 hours" जैसे सापेक्ष व्यंजक स्वीकार नहीं किए जाते। एक रिज़ॉल्व्ड टाइमस्टैम्प भेजें।

शेड्यूल किए गए संदेशों की सूची

जो संदेश दिखाई देने लगे हैं और अभी भेजे जाने का इंतज़ार कर रहे हैं, उन्हें देखने के लिए संदेश सूची को स्थिति के अनुसार फ़िल्टर करें। हो सकता है कि नया स्वीकार किया गया शेड्यूल, सामग्री अपलोड होने या पढ़ने पर मिलने वाली जानकारी अपडेट होने के दौरान, सूची में दिखाई न दे:
for await (const message of bird.email.list({ status: "scheduled" })) {
  console.log(message.id, message.scheduled_at);
}
status=canceled उन संदेशों की सूची देता है जो आपने भेजे जाने से पहले रद्द किए। एक बार शेड्यूल्ड संदेश भेज दिया जाता है तो वह पाइपलाइन में चला जाता है और किसी भी अन्य सेंड की तरह डिलीवरी स्टेटस के साथ दिखाई देता है। डैशबोर्ड का ईमेल लॉग वही Scheduled और Canceled फ़िल्टर प्रदान करता है।

शेड्यूल्ड सेंड रद्द करना

भेजना शुरू होने से पहले किसी भी समय POST /v1/email/messages/{message_id}/cancel से संदेश रद्द करें:
await bird.email.cancel("em_abc123");
सफल रद्दीकरण 204 No Content लौटाता है। संदेश की स्थिति canceled हो जाती है, वह कभी नहीं भेजा जाता, और एक email.canceled वेबहुक फ़ायर होता है। चार बातें जानने योग्य हैं:
  • केवल अभी-शेड्यूल्ड संदेश ही रद्द किया जा सकता है। जो संदेश पहले से भेजना शुरू हो चुका है, भेजा जा चुका है, या पहले ही रद्द किया जा चुका है, वह 409 लौटाता है:
    कोड उदाहरण
    {
      "error": {
        "type": "conflict_error",
        "code": "E10005",
        "name": "EmailNotCancelable",
        "message": "This message cannot be canceled.",
        "remediation": "Only a scheduled message that has not started sending can be canceled. Once sending begins there is no way to pull it back."
      }
    }
    जैसे-जैसे भेजने का समय आता है, रद्दीकरण सेंड के साथ रेस हार भी सकता है और उसी कारण 409 लौटा सकता है।
  • कॉन्टेंट अपलोड होते समय भी आप भेजना रद्द कर सकते हैं। अटैचमेंट या बड़े संदेश वाला शेड्यूल किया गया ईमेल 202 जवाब के बाद भी अपना कॉन्टेंट स्टोर कर रहा हो सकता है। सफलतापूर्वक रद्द करने पर वह रद्द ही रहता है, भले ही अपलोड बाद में पूरा हो जाए।
  • रद्द करने से शेड्यूल्ड-ईमेल कोटा वापस नहीं मिलता। शेड्यूल करते समय आपने जो यूनिट खर्च की वह खर्च रहती है, और यही वह चीज़ है जो शेड्यूल-फिर-रद्द लूप को कोटे से बचने से रोकती है। आपका नियमित सेंड कोटा अप्रभावित रहता है, क्योंकि वह केवल तभी चार्ज होता है जब संदेश वास्तव में भेजा जाता है।
  • रद्दीकरण को फिर से प्रयास करना सुरक्षित है, किसी भी अन्य राइट की तरह Idempotency-Key के साथ।
शेड्यूल्ड सेंड को किसी अलग समय पर ले जाने के लिए, उसे रद्द करें और नए scheduled_at के साथ एक नया सेंड सबमिट करें। आपको एक नई em_ ID मिलेगी।

भेजते समय क्या होता है

शेड्यूलिंग केवल यह बदलती है कि संदेश कब रिलीज़ होता है। उसका निर्माण और शासन वही रहता है। अटैचमेंट, कैटेगरी, टैग, और मेटाडेटा सब ठीक वैसे ही व्यवहार करते हैं जैसे तत्काल सेंड पर, और वेबहुक इवेंट्स पर भी उसी तरह दिखते हैं। पाँच जाँचें दो क्षणों में विभाजित होती हैं:
  • पेलोड और डोमेन वैलिडेशन पहले ही चलता है। गलत तरीके से बना शेड्यूल्ड सेंड API कॉल पर 422 के साथ विफल हो जाता है, ताकि आपको सुबह 9 बजे की बजाय अभी पता चल जाए।
  • भेजने के समय सेंडर डोमेन फिर से जाँचा जाता है। अगर शेड्यूल किया गया समय आने पर आपका from डोमेन अब वेरिफ़ाइड नहीं है, तो संदेश नहीं भेजा जाता। इसके प्राप्तकर्ता अनवेरिफ़ाइड डोमेन से मेल प्राप्त करने की बजाय एक कारण के साथ rejected के रूप में लौटते हैं। पूरी अवधि के लिए डोमेन वेरिफ़ाइड रखें।
  • आपका सेंड कोटा भेजने के समय चार्ज होता है। नियमित सेंड कोटा संदेश भेजे जाने पर खर्च होता है। शेड्यूलिंग कोटे को अपरिवर्तित छोड़ती है। अगर भेजने के समय कोटा समाप्त हो चुका है, तो प्राप्तकर्ता अस्वीकार कर दिए जाते हैं।
  • सप्रेशन भेजने के समय मूल्यांकित होता है, आपकी उस समय की सप्रेशन लिस्ट के अनुसार, ताकि शेड्यूलिंग और भेजने के बीच अनसब्सक्राइब करने वाले व्यक्ति का अनुरोध भी माना जाए।
  • भेजने के समय सहेजा गया टेम्पलेट मौजूद होना चाहिए। अगर आप शेड्यूल करने के बाद टेम्पलेट हटा देते हैं, तो संदेश नहीं भेजा जाता। इसके प्राप्तकर्ता rejected के रूप में generation_failure के साथ लौटते हैं।

त्रुटियाँ

स्टेटसकोडकब
422E10003बिलिंग अवधि के लिए आपके संगठन का शेड्यूल्ड-ईमेल कोटा समाप्त हो गया है
422scheduled_at 30 सेकंड से कम या 30 दिन से अधिक दूर है
422पेलोड पार्क करने के लिए बहुत बड़ा है; बॉडी, प्राप्तकर्ता, या मेटाडेटा कम करें, या अभी भेजें
409E10005संदेश अब रद्द नहीं किया जा सकता: वह पहले से भेजना शुरू हो चुका है, भेजा जा चुका है, या रद्द किया जा चुका है
404संदेश पढ़ने पर उसकी स्वीकृति अभी नहीं दिख रही है, या इस वर्कस्पेस में उस ID का कोई संदेश मौजूद नहीं है

वेबहुक

सामान्य डिलीवरी इवेंट्स के अलावा दो इवेंट शेड्यूलिंग के लिए विशिष्ट हैं:
  • email.scheduled ऐसे संदेश की सूचना देता है जो भविष्य के अपने scheduled_at समय का इंतज़ार कर रहा है। टेम्पलेट से भेजे जाने वाले संदेशों के लिए, चुना गया संस्करण भेजने के समय फिर से लोड किया जाता है और उसकी सामग्री तैयार की जाती है। यह काम पूरा होने से पहले यह इवेंट आ सकता है।
  • email.canceled तब फ़ायर होता है जब कोई शेड्यूल्ड संदेश भेजे जाने से पहले रद्द किया जाता है।
जब संदेश भेजा जाता है, तो सामान्य email.accepted चेन बिना किसी बदलाव के चलती है।
शेड्यूलिंग इवेंट असिंक्रोनस रूप से प्रकाशित होते हैं। email.scheduled प्रकाशित होने से पहले संदेश की शेड्यूल की गई स्थिति बदल सकती है। वेबहुक मिलने का मतलब यह नहीं है कि पढ़ने वाले एंडपॉइंट पहले से वह स्थिति दिखा रहे हैं।

अगले कदम

संबंधित संसाधन

इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ