PHP

زمان‌بندی و لغو

`scheduledAt`، `emails->reschedule`، `emails->update` و `emails->cancel`.

ارسال در آینده

schedule.php

$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 در کنارش، فیلد را می‌افزاید و پیام اصلی را دست‌نخورده می‌گذارد.

یک DateTimeInterface، در هر منطقهٔ زمانی که ساخته شده باشد، به‌صورت یک لحظه با UTC فرستاده می‌شود، پس ساعت 09:00 در Europe/London همان لحظه‌ای که نام می‌برد فرستاده می‌شود. رشتهٔ تاریخی بدون ساعت، مانند 2027-01-01، نیمه‌شب UTC همان روز خوانده می‌شود، پس وقتی ساعت مهم است یک لحظه بدهید.

جابه‌جایی و توقف

reschedule.php

$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 را پرتاب می‌کند، چون بخشی از آن پیش از این در صندوق کسی است. لغوِ پیامی که از پیش لغو شده موفق می‌شود و چیزی را تغییر نمی‌دهد.

برای یافتن آنچه در یک بازه منتظر رفتن است، با status: ['scheduled', 'queued'] و scheduledFrom: و scheduledTo: فهرست بگیرید، همان‌طور که تقویم برنامه انجام می‌دهد.

تغییر آن پیش از رفتن

emails->update پیامی را که هنوز نرفته تغییر می‌دهد: زمان رفتنش را با scheduledAt، آنچه می‌گوید را با subject، html و text، نشانی‌ای که از آن می‌رود را با from، و اینکه به چه کسانی می‌رود را با to، cc و bcc. هر ترکیبی از آن‌ها را با هم بفرستید، و فیلدی که جا بگذارید مقدارش را نگه می‌دارد. یک فهرست گیرندگان، فهرست ذخیره‌شده را به‌طور کامل جایگزین می‌کند. این همان کاری است که ویرایش یک پیام زمان‌بندی‌شده در تقویم برنامه انجام می‌دهد.

update.php

$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 همان‌طور بررسی می‌شود که در ارسال، پس باید نشانی‌ای باشد که کلید اجازهٔ ارسال با آن را دارد. پیامی که هنگام پذیرفته شدن ترجمه شده متن تأییدشده‌اش را نگه می‌دارد، پس subject، html یا text تازه روی آن یک 409 translation_locked است، و پیامی که پیش از زمان‌بندی رمزگذاری شده متن و گیرندگانش را نگه می‌دارد. این پیام‌ها را لغو کنید و به‌جایش دوباره بفرستید.

به‌جایش یک پنجرهٔ لغو

undo_window.php

$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;

پیام زمان‌بندی‌شده تا وقتی نرفته از پیش قابل لغو است، پس این دو را نمی‌شود با هم به کار برد و سرور ردش می‌کند. این یکی را برای پنجرهٔ لغو ارسال روی یک پیام فوری به کار ببرید.

پارامترها: زمان‌بندی

scheduledAtDateTimeInterface or string: زمان ارسال، روی `emails->send`: یک `DateTimeInterface`، یک لحظهٔ ISO 8601 به‌صورت رشته، یا مدتی مانند `PT1H` یا `P2D`. `DateTimeInterface` به‌صورت لحظهٔ UTC فرستاده می‌شود و رشته همان‌طور که هست، و رشتهٔ تاریخی بدون ساعت یعنی نیمه‌شب UTC. دست‌کم یک ثانیه در آینده و حداکثر 365 روز بعد، که گذشتن از هر دو کران یک `validation_error` روی `scheduledAt` است، و زبان طبیعی پذیرفته نمی‌شود، چون تفسیر نادرستِ «سه‌شنبهٔ بعد» پیامی را در زمانی می‌فرستد که دیگر نمی‌شود پسش گرفت.
cancellableForSecondsint: پنجرهٔ لغو ارسال روی یک ارسال «فوری»: یک int از 0 تا 900 با پیش‌فرض 0. هر مقدار بالای 0 در کنار `scheduledAt` رد می‌شود، که از پیش تا وقتی نرفته قابل لغو است، و پیامی که این‌طور نگه داشته شود به‌جای `scheduled` روی `queued` می‌نشیند. همان سازوکار تعویق است با تأخیری کوتاه.
$idstringالزامی: شناسهٔ `msg_`، و نخستین آرگومان `emails->cancel`، `emails->reschedule` و `emails->update`. این‌ها به‌جای اسکوپی از آنِ خودشان به `emails:send` نیاز دارند، و شناسه را درون فضای کاری خودِ کلید جست‌وجو می‌کنند، پس شناسه‌ای متعلق به فضای کاری دیگر دقیقاً مثل شناسه‌ای که هرگز وجود نداشته یک `not_found_error` است.
$scheduledAtDateTimeInterface or stringالزامی: زمان تازه، به‌عنوان آرگومان دوم `emails->reschedule`، که با همان قواعد و در برابر همان پنجرهٔ یک‌ساله خوانده می‌شود. تنها چیزی است که `reschedule` تغییر می‌دهد، و کلاینت چیز دیگری نمی‌فرستد. مدت نسبت به زمانی است که «سرور» آن را می‌خواند، پس زمان‌بندی دوباره‌ای که دوباره تلاش شود کمی دیرتر از اولی می‌نشیند: دیرتر، هرگز زودتر.
apiKeystring: آرگومانی نام‌دار روی هر یک از این سه فراخوانی. به‌جای کلید کلاینت با این کلید عمل می‌کند.

پاسخ

cancel، reschedule و update هرکدام کل پیام را به‌صورت آرایه‌ای که کلیدهایش نام‌های camelCase در API هستند برمی‌گردانند.

objectstring: همیشه `email`. این فراخوانی‌ها به‌جای یک تأییدیه با کل پیام پاسخ می‌دهند، پس برای دیدن آنچه تغییر کرده لازم نیست چیزی دوباره گرفته شود. `emails->send` همین شکل را به‌علاوهٔ `replayed` برمی‌گرداند.
idstring: دستگیرهٔ `msg_`. تا پایان عمر پیام پایدار است و همان شناسه‌ای است که هر فراخوانی دیگری روی آن می‌گیرد.
statusstring: پس از لغو برابر `cancelled` و پس از زمان‌بندی دوباره برابر `scheduled`، از جمله برای پیامی که فقط پشت یک پنجرهٔ لغو `queued` بوده و زمان‌بندی دوباره آن را به زمان‌بندی واقعی تبدیل می‌کند. فقط پیام‌های `queued` و `scheduled` را می‌شود جابه‌جا یا متوقف کرد. هر چیزی جلوتر از آن یک `ConflictException` پرتاب می‌کند که `errorCode` آن `email_not_cancellable` است، چون بخشی از آن پیش از این در صندوق کسی است.
scheduledAtstring or null: لحظهٔ ISO 8601 که پیام باید روانه شود. هم برای پنجرهٔ لغو تنظیم می‌شود و هم برای ارسال با `scheduledAt`، چون این دو یک سازوکارند، و روی ارسال فوریِ ساده null است.
cancellableUntilstring or null: زمانی که لغو دیگر کار نمی‌کند، که روی هر دو مسیر تعویق همان لحظهٔ `scheduledAt` است. روی ارسال فوری null است، که تا وقتی فراخوانی برگردد پیش از این رفته است.
sentAtstring or null: زمانی که پیام واقعاً رفت. تا وقتی منتظر است null است، و روی پیامی که لغو شده برای همیشه null.
messageIdstring or null: همان Message-ID مربوط به RFC 5322، که تا وقتی MIME وجود نداشته باشد null است، پس روی هر پیامی که این فراخوانی‌ها بتوانند رویش کار کنند همیشه null است. چیزی نیست که با آن API را خطاب کنید، و چیزی هم نیست که bounce بعدی با آن برگردد: سرویس ارسال سرآیند را در مسیر خروج بازنویسی می‌کند.
threadIdstring or null: رشته‌ای که این پیام به آن تعلق دارد، که از درخواست گرفته می‌شود و به محض ارسال با هر چه لایهٔ انتقال گزارش کند بازنویسی می‌شود. وقتی پاسخ نباشد null است.
transportstring or null: بایت‌ها چگونه رفتند، که تا پیش از ارسال null است، پس روی هر پیامی که لغو یا زمان‌بندی دوباره بتواند برگرداند null است. ارسال در حالت test مقدار `test` را ثبت می‌کند، و ممکن است لایهٔ انتقالی ظاهر شود که این بسته هنوز نامش را نمی‌برد، پس با مقدار ناشناخته به‌عنوان اطلاعات رفتار کنید نه خطا.
attemptsint: چند بار فرایند ارسال این ردیف را برداشته است. با هر برداشتن بالا می‌رود نه با ارسال موفق، و برای هر چیزی که هنوز منتظر است 0 است.
lastErrorstring or null: آخرین شکست ثبت‌شده برای پیام، که تا وقتی چیزی شکست نخورده null است. ارسالی به‌تعویق‌افتاده که کارش نتوانسته در صف قرار گیرد همین‌جا به شکل `Could not schedule: …` نوشته و به `failed` منتقل می‌شود، و این تنها راهی است که پیامی زمان‌بندی‌شده بدون درخواست کسی از قابل‌لغو بودن می‌افتد.
fromstring: نشانی‌ای که پیام مجاز شمرده شد با آن بیرون برود: همان `from` ارسال‌شده، که خام و با حروف کوچک ذخیره می‌شود. هر نام نمایشی اینجا انداخته می‌شود، چون فیلتر `from:` در `emails->list` بر اساس برابری مقایسه می‌کند.