शेड्यूल की गई भेजाई

किसी संदेश को किसी तय समय तक रोके रखने के लिए 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"

msg = client.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",
)
print(msg.id, msg.status)

package main

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

	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:        "news@yourdomain.com",
		To:          []string{"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:    bird.CategoryMarketing,
		ScheduledAt: time.Date(2027, 1, 15, 9, 0, 0, 0, time.UTC),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $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',
    scheduledAt: new \DateTimeImmutable('2027-01-15T09:00:00Z'),
);
echo $message->getId(), ' ', $message->getStatus();

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

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

कॉल तुरंत 202 Accepted लौटाती है, जिसमें em_ उपसर्ग वाली संदेश ID और status: accepted होते हैं। यह वही संदेश ऑब्जेक्ट है जो तुरंत भेजाई लौटाती है, साथ में UTC में लौटाया गया scheduled_at भी होता है। इससे आप अलग से पढ़े बिना भेजने के समय की पुष्टि कर सकते हैं। अनुरोध तुरंत स्वीकार होता है, जबकि डिलीवरी बाद में होती है। अगर आप अनुरोध में scheduled_at नहीं देते, तो संदेश तुरंत भेजा जाता है और उसकी प्रतिक्रिया में scheduled_at कुंजी नहीं होती।

रीड असिंक्रोनस रूप से अपडेट होते हैं। अभी शेड्यूल किया गया संदेश शुरू में Get a message से 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 कुंजी नहीं होती; बैच संदर्भ एक ही प्रतिक्रिया में दोनों दिखाता है।

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

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

scheduled_at एक निरपेक्ष RFC 3339 टाइमस्टैम्प है। इस पर दो नियम लागू होते हैं:

• समय भविष्य में 30 सेकंड से 30 दिन के बीच होना चाहिए। 30 सेकंड से कम या 30 दिन से अधिक दूर का समय 422 के साथ अस्वीकार हो जाता है। न्यूनतम सीमा इसलिए है ताकि शेड्यूल तुरंत भेजे जाने वाले संदेश से होड़ न करे। हम किसी संदेश को अधिकतम 30 दिन तक रोककर रखते हैं।
• सटीक क्षण दें। 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);
}

for message in client.email.list(status="scheduled"):
    print(message.id, message.scheduled_at)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusScheduled}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}

foreach ($bird->email->list(['status' => 'scheduled']) as $message) {
    echo $message->getId(), "\n";
}

bird email list --status scheduled

curl "https://us1.platform.bird.com/v1/email/messages?status=scheduled" \
  -H "Authorization: Bearer bk_us1_..."

status=canceled उन संदेशों को सूचीबद्ध करता है जिन्हें आपने भेजे जाने से पहले रद्द कर दिया था। शेड्यूल किया गया संदेश भेजे जाने का समय आने पर पाइपलाइन में चला जाता है और किसी भी अन्य भेजे गए संदेश की तरह डिलीवरी स्टेटस के साथ दिखता है। डैशबोर्ड का ईमेल लॉग भी यही Scheduled और Canceled फ़िल्टर देता है।

शेड्यूल किए गए संदेश को रद्द करना

संदेश भेजा जाना शुरू होने से पहले किसी भी समय आप उसे POST /v1/email/messages/{message_id}/cancel से रद्द कर सकते हैं:

await bird.email.cancel("em_abc123");

client.email.cancel("em_abc123")

if err := client.Email.Cancel(context.Background(), "em_abc123"); err != nil {
	log.Fatal(err)
}

$bird->email->cancel('em_01krdgeqcxet5s7t44vh8rt9mg');

bird email cancel <message-id> --yes

curl -X POST "https://{region}.platform.bird.com/v1/email/messages/{message_id}/cancel" \
  -H "Authorization: Bearer $TOKEN"

सफल रद्दीकरण पर 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 के रूप में लौटते हैं। पूरी अवधि के दौरान डोमेन को सत्यापित रखें।
• आपकी सेंड सीमा भेजने के समय घटती है। सामान्य सेंड कोटा तब खर्च होता है जब संदेश भेजा जाता है। शेड्यूल करने से कोटा नहीं बदलता। अगर भेजने के समय सीमा खत्म हो चुकी है, तो प्राप्तकर्ता अस्वीकार कर दिए जाते हैं।
• सप्रेशन का मूल्यांकन भेजने के समय होता है, उस समय की आपकी सप्रेशन सूची के आधार पर, इसलिए जो व्यक्ति शेड्यूल करने और भेजने के बीच अनसब्सक्राइब करता है, उसकी पसंद का भी पालन होता है।
• भेजने के समय संग्रहीत टेम्पलेट मौजूद होना चाहिए। अगर आप शेड्यूल करने के बाद टेम्पलेट हटा देते हैं, तो संदेश नहीं भेजा जाता। उसके प्राप्तकर्ता generation_failure के साथ rejected के रूप में लौटते हैं।

त्रुटियाँ

वेबहुक

सामान्य डिलीवरी इवेंट के अलावा, दो इवेंट विशेष रूप से शेड्यूलिंग से जुड़े हैं:

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

संदेश भेजे जाने पर सामान्य email.accepted क्रम बिना किसी बदलाव के चलता है।

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

आगे के कदम

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