शेड्यूल और रद्द करना
`scheduledAt`, `emails->reschedule`, `emails->update` और `emails->cancel`।
बाद में भेजना
$message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',]; $client->emails->send([...$message, 'scheduledAt' => 'PT1H']);$client->emails->send([...$message, 'scheduledAt' => new \DateTimeImmutable('2027-01-01 09:00', new \DateTimeZone('UTC'))]);$client->emails->send([...$message, 'scheduledAt' => '2027-01-01T09:00:00.000Z']);एक DateTimeInterface, स्ट्रिंग के रूप में ISO 8601 क्षण, या PT1H या P2D जैसी अवधि। अधिकतम एक साल आगे तक, अतीत में कभी नहीं। पहले बनाए गए संदेश को scheduledAt के साथ एक नए array में फैलाने से यह फ़ील्ड जुड़ जाता है और मूल संदेश जस का तस रहता है।
DateTimeInterface चाहे जिस zone में बना हो, UTC में एक क्षण के रूप में भेजा जाता है, इसलिए Europe/London का 09:00 उसी क्षण के रूप में जाता है जिसे वह दर्शाता है। बिना समय वाली तारीख़ की स्ट्रिंग, जैसे 2027-01-01, उस दिन की UTC आधी रात के रूप में पढ़ी जाती है, इसलिए जब घंटा मायने रखता हो तो क्षण पास करें।
खिसकाना और रोकना
$message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',]; $queued = $client->emails->send([...$message, 'scheduledAt' => 'PT1H']); $client->emails->reschedule($queued['id'], new \DateTimeImmutable('+1 day'));$client->emails->cancel($queued['id']);सिर्फ़ queued और scheduled संदेश रोके जा सकते हैं। इससे आगे की कोई भी स्थिति ConflictException throw करती है, क्योंकि उसका कुछ हिस्सा पहले ही किसी के मेलबॉक्स में है। पहले से रद्द संदेश को रद्द करना सफल होता है और कुछ नहीं बदलता।
किसी समय-सीमा में जाने के लिए क्या इंतज़ार कर रहा है यह जानने के लिए status: ['scheduled', 'queued'] और scheduledFrom: तथा scheduledTo: के साथ सूची लें, जैसा ऐप का कैलेंडर करता है।
जाने से पहले उसे बदलना
emails->update ऐसे संदेश को बदलता है जो अभी गया नहीं है: वह कब जाएगा scheduledAt से, वह क्या कहता है subject, html और text से, वह किस पते से जाएगा from से, और किसे जाएगा to, cc और bcc से। इनमें से कोई भी साथ में भेजें, और जो फ़ील्ड आप छोड़ देते हैं वह अपना मान बनाए रखता है। प्राप्तकर्ताओं की सूची सहेजी गई सूची को पूरी तरह बदल देती है। ऐप के कैलेंडर में शेड्यूल किए गए संदेश को संपादित करने पर यही होता है।
$updated = $client->emails->update('msg_3f9a1c07d2b84e6a9c5b1f20', [ 'subject' => 'Your September invoice, corrected', 'to' => ['[email protected]', '[email protected]'], 'scheduledAt' => new \DateTimeImmutable('2026-10-05 08:00', new \DateTimeZone('UTC')),]); echo $updated['status'], ' ', $updated['subject'], ' ', $updated['scheduledAt'], PHP_EOL;from की जाँच वैसे ही होती है जैसे send पर, इसलिए यह ऐसा पता होना चाहिए जिससे कुंजी भेज सकती है। जो संदेश स्वीकार होते समय अनूदित हुआ वह अपने स्वीकृत शब्द बनाए रखता है, इसलिए उस पर नया subject, html या text 409 translation_locked है, और जो शेड्यूल होने से पहले एन्क्रिप्ट हुआ वह अपने शब्द और प्राप्तकर्ता बनाए रखता है। ऐसे संदेशों को रद्द करें और इसकी जगह फिर से भेजें।
इसके बजाय एक undo खिड़की
$message = [ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',]; $held = $client->emails->send([...$message, 'cancellableForSeconds' => 30]); echo $held['status'], ' ', $held['cancellableUntil'], PHP_EOL;निर्धारित संदेश तो जाने तक वैसे भी रद्द किया जा सकता है, इसलिए दोनों को मिलाया नहीं जा सकता और सर्वर इसे अस्वीकार करता है। तत्काल संदेश पर undo-send खिड़की के लिए इसी का उपयोग करें।
पैरामीटर: निर्धारण
scheduledAtDateTimeInterface or string- `emails->send` पर कब भेजना है: एक `DateTimeInterface`, स्ट्रिंग के रूप में ISO 8601 क्षण, या `PT1H` या `P2D` जैसी अवधि। `DateTimeInterface` UTC क्षण के रूप में और स्ट्रिंग जैसी है वैसी भेजी जाती है, और बिना समय वाली तारीख़ की स्ट्रिंग का मतलब UTC आधी रात है। भविष्य में कम से कम एक सेकंड और अधिकतम 365 दिन आगे, और किसी भी सीमा के बाहर होने पर `scheduledAt` पर `validation_error`, और सामान्य भाषा स्वीकार नहीं की जाती, क्योंकि “अगले मंगलवार” को ग़लत समझने से संदेश ऐसे समय पर चला जाता है जिसे वापस नहीं लिया जा सकता।
cancellableForSecondsint- “तुरंत” send पर undo-send की अवधि: 0 से 900 तक का एक int, डिफ़ॉल्ट 0। 0 से ऊपर का कोई भी मान `scheduledAt` के साथ अस्वीकार किया जाता है, जो जाने तक पहले से रद्द किया जा सकता है, और इस तरह रोका गया संदेश `scheduled` के बजाय `queued` पर रहता है। यह छोटी देरी वाला वही टालने का तंत्र है।
$idstringआवश्यक- `msg_` id, और `emails->cancel`, `emails->reschedule` तथा `emails->update` का पहला argument। इन्हें अपने किसी scope के बजाय `emails:send` चाहिए, और ये id को कुंजी के अपने वर्कस्पेस में खोजते हैं, इसलिए किसी दूसरे वर्कस्पेस की id ठीक उसी तरह `not_found_error` है जैसे कभी न रही id।
$scheduledAtDateTimeInterface or stringआवश्यक- नया समय, `emails->reschedule` के दूसरे argument के रूप में, उन्हीं नियमों से और उसी एक साल की सीमा के भीतर पढ़ा जाता है। `reschedule` सिर्फ़ यही बदलता है, और क्लाइंट और कुछ नहीं भेजता। अवधि उस समय के सापेक्ष होती है जब “सर्वर” उसे पढ़ता है, इसलिए दोबारा आज़माया गया reschedule पहले वाले की तुलना में थोड़ा बाद में पड़ता है: बाद में, पहले कभी नहीं।
apiKeystring- तीनों में से किसी भी कॉल पर एक named आर्ग्युमेंट। क्लाइंट की कुंजी के बजाय इस कुंजी से काम करता है।
प्रतिक्रिया
cancel, reschedule और update में से हर एक पूरा संदेश API के camelCase नामों वाली कुंजियों के array के रूप में लौटाता है।
objectstring- हमेशा `email`। ये कॉल किसी पावती के बजाय पूरे संदेश के साथ जवाब देती हैं, इसलिए क्या बदला यह देखने के लिए कुछ भी दोबारा नहीं लाना पड़ता। `emails->send` यही आकार लौटाता है, साथ में `replayed`।
idstring- `msg_` हैंडल। संदेश के पूरे जीवनकाल में स्थिर, और वही id जो उस पर हर दूसरी कॉल लेती है।
statusstring- रद्द करने के बाद `cancelled` और फिर से शेड्यूल करने के बाद `scheduled`, उस संदेश के लिए भी जो undo अवधि के पीछे सिर्फ़ `queued` था, जिसे फिर से शेड्यूल करना असली शेड्यूल में बदल देता है। सिर्फ़ `queued` और `scheduled` संदेश खिसकाए या रोके जा सकते हैं। इससे आगे की कोई भी स्थिति ऐसा `ConflictException` throw करती है जिसका `errorCode` `email_not_cancellable` है, क्योंकि उसका कुछ हिस्सा पहले ही किसी के मेलबॉक्स में है।
scheduledAtstring or null- वह ISO 8601 क्षण जब संदेश dispatch होना है। undo अवधि के लिए भी सेट होता है और `scheduledAt` वाले send के लिए भी, क्योंकि दोनों एक ही तंत्र हैं, और सादे तुरंत send पर null।
cancellableUntilstring or null- रद्द करना कब काम करना बंद करता है, जो टाले गए दोनों रास्तों पर `scheduledAt` वाला ही क्षण है। तुरंत send पर null, जो कॉल लौटने तक पहले ही जा चुका होता है।
sentAtstring or null- संदेश वास्तव में कब गया। इंतज़ार के दौरान null, और रद्द किए गए संदेश पर हमेशा null।
messageIdstring or null- RFC 5322 Message-ID, MIME बनने तक null, इसलिए जिन संदेशों पर ये कॉल काम कर सकती हैं उन पर हमेशा null। यह API में किसी चीज़ को संबोधित करने के लिए नहीं है, और न ही बाद में आने वाला bounce इसके आधार पर लौटता है: भेजने वाली सेवा बाहर जाते समय हेडर को फिर से लिखती है।
threadIdstring or null- वह thread जिसका यह संदेश है, रिक्वेस्ट से लिया गया और भेजे जाने के बाद transport जो बताता है उससे फिर से लिखा गया। जब यह जवाब न हो तो null।
transportstring or null- बाइट्स कैसे गए, और dispatch होने तक null, इसलिए रद्द करने या फिर से शेड्यूल करने से लौटने वाले हर संदेश पर null। test-mode send `test` दर्ज करता है, और ऐसा transport भी दिख सकता है जिसका नाम यह पैकेज अभी नहीं लेता, इसलिए अज्ञात मान को error के बजाय जानकारी मानें।
attemptsint- भेजने की प्रक्रिया ने इस पंक्ति पर कितनी बार दावा किया। यह सफल send से नहीं, हर दावे के साथ बढ़ता है, और जो अभी इंतज़ार में है उसके लिए 0 है।
lastErrorstring or null- संदेश के लिए दर्ज आख़िरी विफलता, जब तक कुछ विफल न हुआ हो तब तक null। जिस टाले गए send का जॉब queue में नहीं डाला जा सका, उसे यहाँ `Could not schedule: …` के रूप में लिखा जाता है और `failed` में ले जाया जाता है, और यही एकमात्र तरीक़ा है जिससे कोई शेड्यूल किया गया संदेश बिना किसी के कहे रद्द करने योग्य नहीं रहता।
fromstring- वह पता जिससे संदेश को बाहर जाने की अनुमति मिली: भेजा गया `from`, सादे और छोटे अक्षरों में सहेजा गया। कोई भी display name यहाँ हटा दिया जाता है, क्योंकि `emails->list` का `from:` फ़िल्टर बराबरी पर तुलना करता है।