دامنه‌ها
`domains->list`، `listAll`، `iterate`، `get` و `update`.
همهٔ متدها
$page = $client->domains->list(); foreach ($page as $row) { echo $row['domain'], ' ', $row['sending']['canSend'] ? 'can send' : 'cannot send yet', PHP_EOL;} $domain = $client->domains->get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f');echo $domain['receiving']['verified'] ? 'receiving' : 'not verified yet', ' ', $domain['sending']['status'], PHP_EOL; foreach ($domain['addresses'] as $entry) { echo $entry['address'], ' ', $entry['enabled'] ? 'on' : 'off', PHP_EOL;}دریافت و ارسال دو واقعیت مستقل‌اند و به‌صورت دو آرایه بازگردانده می‌شوند. receiving.verified یعنی MX دامنه ایمیلش را به اینجا می‌آورد و چالش مالکیتش منتشر شده است. sending بررسی امضای خروجی را گزارش می‌دهد: status یکی از verified، pending، failed، no_identity یا unknown است، و canSend می‌گوید آیا ارسالی از این دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفیِ قدیمی‌تر از یک روز به‌جای رد شدن، ناشناخته در نظر گرفته می‌شود، پس به‌جای status روی canSend شاخه بزنید، که به شکل $domain['sending']['canSend'] خوانده می‌شود.
list یک OpenEmail\Result\Page از دامنه‌ها به ترتیب الفبایی برمی‌گرداند، و listAll همه را در یک آرایه برمی‌گرداند. iterate یک Generator برمی‌گرداند که آن‌ها را یکی‌یکی yield می‌کند.
$domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; $updated = $client->domains->update($domainId, ['trackingHost' => 'links.acme.com']);$record = $updated['tracking']['record'];echo $updated['tracking']['status'], ' ', $record['name'] ?? '', ' ', $record['value'] ?? '', PHP_EOL; $client->domains->update($domainId, ['trackingHost' => null]);update دامنهٔ ردیابی اختصاصی دامنه را، یعنی زیردامنه‌ای مانند links.acme.com، تنظیم می‌کند، دوباره بررسی می‌کند یا برمی‌دارد، و همان آرایه‌ای را برمی‌گرداند که get. tracking در هر خواندن آن را گزارش می‌دهد. تا وقتی بررسی‌ای موفق نشود، tracking.status برابر pending است و پیوندهای ردیابی‌شده و pixel باز شدن همچنان از میزبان پیش‌فرض OpenEmail استفاده می‌کنند. وقتی بررسی‌ای موفق شود، active می‌شود و ایمیل‌های تازهٔ این دامنه برای هر دو از دامنهٔ ردیابی استفاده می‌کنند.
get نشانی‌های روی دامنه را هم فهرست می‌کند. addresses->list فراخوانی مرتبط است: نشانی‌هایی که این کلید می‌تواند در سرآیند From بگذارد، که محدودتر است، هرکدام با یک حکم canSend. یک OpenEmail\Result\AddressBookPage برمی‌گرداند که آن‌ها را به‌جای items در addresses نگه می‌دارد، در کنار domains و unrestricted. listAll آن یک OpenEmail\Result\AddressBook برمی‌گرداند.
appHost فضای نامی از آنِ خودش است، $client->appHost. get، set، verify و delete نشانی برنامهٔ وب فضای کاری را می‌خوانند و تغییر می‌دهند، یعنی زیردامنه‌ای مانند mailbox.acme.com روی یکی از این دامنه‌ها یا هر دامنهٔ دیگری که در اختیار فضای کاری است، که افراد فضای کاری آنجا با برند فضای کاری وارد می‌شوند. set رکوردهای DNS را که باید منتشر شوند برمی‌گرداند، در record و، برای دامنه‌ای بیرون از فضای کاری، ownershipRecord. delete، و setی که نشانی‌ای را جایگزین می‌کند، از برنامهٔ OAuth کد تأیید هویت می‌خواهند: تا وقتی کدی نداشته باشد، فراخوانی یک 403 را پرتاب می‌کند که isStepUpRequired() آن true است.
branding آن برند را تنظیم می‌کند. branding->get پیوندهای نشان، لوگو، لوگوی حالت تیره و عکس صفحهٔ ورود، دو قلم و پس‌زمینهٔ ورود را می‌خواند. branding->update قلم‌ها و پس‌زمینه را تغییر می‌دهد، branding->uploadImage($variant, $data, contentType: ...) یکی از چهار تصویر را بارگذاری می‌کند، و branding->removeImage($variant) یکی را حذف می‌کند. گونه یکی از mark، wordmark، wordmark-dark یا login-background است، و OpenEmail\Constants\BrandImageVariants آن‌ها را نام می‌برد. داده یک رشتهٔ بایتی، یک منبع stream، یک SplFileInfo یا یک stream یا فایل بارگذاری‌شدهٔ PSR-7 است. یک SplFileInfo مانند new \SplFileInfo('logo.svg')، یک stream که روی فایلی باز شده، یا یک بارگذاری Laravel یا Symfony نوعش را با خود می‌آورد. بایت‌های دیگر به contentType: نیاز دارند، و تصویر بدون نوع با یک 422 invalid_image رد می‌شود. لوگو همان چیزی است که به نشانی برنامهٔ وب و، در طرح پولی، به ایمیل‌هایی که برای فضای کاری فرستاده می‌شوند برند می‌دهد.
پارامترها: domains->get
idstringالزامی- شناسه از `domains->list`، یک UUID که هنگام افزودن دامنه ساخته شده، نه نام میزبان، پس `get('example.com')` چیزی پیدا نمی‌کند. جست‌وجو علاوه بر شناسه به فضای کاری خودِ کلید هم محدود است، پس دامنهٔ فضای کاری دیگر به‌جای 403 یک 404 است که به‌صورت `NotFoundException` پرتاب می‌شود. شناسهٔ خالی پیش از فرستادن هر چیزی `InvalidArgumentException` را پرتاب می‌کند.
پارامترها: domains->update
idstringالزامی- همان domain id که `get` می‌گیرد. scope مورد نیاز آن `domains:write` است.
trackingHoststring or null- زیردامنه‌ای از همان دامنه، حداکثر 512 نویسه، مانند `links.acme.com`. فاصله‌های اضافی حذف و حروف کوچک می‌شوند، و `https://` یا `http://` ابتدایی، مسیر و نقطهٔ انتهایی حذف می‌شوند. مقدار تازه در همان فراخوانی اعتبارسنجی، ذخیره و بررسی می‌شود. مقداری که دامنه از پیش دارد بررسی را دوباره اجرا می‌کند، مگر آنکه بررسی قبلی کمتر از 30 ثانیه پیش بوده باشد. برای برداشتن دامنهٔ ردیابی null یا یک رشتهٔ خالی بدهید، و برای دست نزدن به آن، این کلید را ننویسید.
میزبانی که رد شود یک ApiException را پرتاب می‌کند که در param نام trackingHost را می‌برد: یک 422 invalid_tracking_host برای نامی که قابل استفاده نیست، مثلاً نامی بیرون از دامنه، یک 409 domain_not_verified برای میزبان تازه وقتی receiving.verified برابر false است و رکورد TXT دامنه با نام _openemail-challenge هنوز منتشر نشده، و یک 409 tracking_host_in_use برای نامی که دامنهٔ دیگری از پیش به کار می‌برد، یا وقتی دامنهٔ ردیابی را سرور OpenEmail دیگری مدیریت می‌کند. 422 به‌صورت ValidationException می‌رسد و هر 409 به‌صورت ConflictException. کلیدی که به نشانی‌های خاصی محدود است یک 422 capability_unsupported می‌گیرد، چون دامنهٔ ردیابی روی همهٔ نشانی‌های دامنه اعمال می‌شود.
وصله یک آرایه است که کلیدهایش نام‌های camelCase در API هستند، پس کلیدی مانند tracking_host همان‌طور که نوشته شده فرستاده و با یک 422 unknown_parameter رد می‌شود. update همچنین catchAll، storageHost برای دامنهٔ فایل‌ها مانند files.acme.com، و dmarcPolicy را می‌گیرد. همهٔ کلیدها اختیاری‌اند و مرجع متدها هرکدام را پوشش می‌دهد. کلاینت متد update را مانند یک خواندن دوباره امتحان می‌کند، چون تکرار، میزبان را از پیش تنظیم‌شده می‌یابد و حداکثر دوباره بررسی‌اش می‌کند.
پاسخ: یک دامنه (domains->get)
objectstring- همیشه رشتهٔ `domain`، هم روی ردیف‌های `list` و هم روی همین یکی.
idstring- UUID دامنه. در تمام عمر آن ردیف پایدار است، و تنها دستگیره‌ای است که دیگر فراخوانی‌های دامنه می‌پذیرند.
domainstring- نام میزبان خالی، با حروف کوچک: `example.com`. در کل محصول یکتاست، یک مالک برای هر دامنه، پس دو فضای کاری نمی‌توانند هر دو مدعی آن شوند.
receiving.verifiedbool- به محض اینکه DNS نشان دهد MX دامنه میزبانی را نام می‌برد که نامه‌اش را به اینجا می‌آورد، و در جایی که ردیف یک توکن چالش دارد، رکورد TXT متناظر `_openemail-challenge` را هم نشان دهد، True می‌شود. MX به‌تنهایی چیزی را ثابت نمی‌کند، چون هر دامنه‌ای که برایش نامه دریافت می‌کنیم همان نام‌های میزبان را منتشر می‌کند؛ توکن به همین دلیل وجود دارد، و به همین دلیل این پرچم همان دروازه‌ای است که تحویل ورودی پیش از پذیرش نامه بررسی می‌کند.
receiving.verifiedAtstring or null- زمان موفق شدن تأیید، به‌صورت یک رشته با قالب ISO 8601. تا وقتی تأیید نشده null است، و `verified` دقیقاً از همین ستون مشتق می‌شود، پس این دو هرگز نمی‌توانند با هم ناسازگار باشند.
receiving.catchAllbool- اینکه آیا هر local-partی پذیرفته می‌شود یا نه. برای دامنه‌هایی که پس از قاعده شدنِ این افزوده شده‌اند به‌طور پیش‌فرض روشن است. با خاموش بودنش، فقط نشانی‌های نام‌برده روی دامنه پذیرفته می‌شوند و بقیه در زمان SMTP رد می‌شوند، پس فرستنده به‌جای سکوت یک bounce می‌گیرد.
receiving.lastCheckedAtstring or null- آخرین باری که دربارهٔ این دامنه از DNS پرسیده شد. وقتی هرگز از DNS پرسیده نشده null است، که برای کسی که یک دقیقه پیش دامنه‌ای افزوده، معنایی بسیار متفاوت از شکست دارد. خواندن دامنهٔ تأییدنشده، وقتی آخرین بررسی بیش از 20 ثانیه قدمت داشته باشد، دوباره از DNS می‌پرسد، پس فراخوانی پیاپی `get` یکی از راه‌های منتظر ماندن برای تأیید است، و `verify` بی‌درنگ بررسی می‌کند.
receiving.errorstring or null- چرا آخرین بررسی موفق نشد، با عبارتی که مالک بتواند بر اساس آن اقدام کند: `No MX records yet. DNS changes can take a few minutes to spread.` نمونه‌ای معمول است. به محض موفق شدن بررسی null می‌شود، و ذخیره می‌شود نه مشتق، تا بارگذاری دوباره و بررسی دوبارهٔ زمان‌بندی‌شده یک چیز بگویند.
sending.statusstring- وضعیت امضای خروجی، همان‌طور که آخرین بررسی آن را دید: `verified`، `pending`، `failed`، `no_identity` یا `unknown`. از بررسی ذخیره‌شده خوانده می‌شود، پس `sending.checkedAt` می‌گوید چقدر قدیمی است.
sending.canSendbool- اینکه آیا ارسال از این دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفیِ قدیمی‌تر از یک روز به‌جای رد، نامعلوم در نظر گرفته می‌شود، پس این می‌تواند true باشد در حالی که `status` برابر `pending` است. پیش از ارسال روی همین شاخه بزنید: مقدار false یعنی `emails->send` از این دامنه با یک 409 `domain_not_sendable` رد می‌شود.
sending.checkedAtstring or null- آخرین باری که وضعیت امضا بررسی شده، به‌صورت یک رشته با قالب ISO 8601. وقتی هرگز بررسی نشده null است، که معنایی بسیار متفاوت از شکست دارد.
sending.errorstring or null- آخرین شکست امضا به‌صورت متن، یا null به‌محض موفقیت.
sending.notestring- یکی از پنج جمله، که بر پایهٔ `sending.status` انتخاب می‌شود و می‌گوید آن وضعیت به زبانی که صاحب دامنه بتواند بر اساسش اقدام کند چه معنایی دارد. نثری برای خواندن آدم است، پس به‌جای این، روی `sending.canSend` شاخه بزنید.
trackingarray- دامنهٔ ردیابی اختصاصی این دامنه، هم روی ردیف‌های `list` و هم روی همین یکی، و همان چیزی که `update` تغییرش می‌دهد.
tracking.hoststring or null- دامنهٔ ردیابی، مانند `links.acme.com`، یا null وقتی چیزی تنظیم نشده باشد.
tracking.statusstring- `none` یعنی هیچ دامنهٔ ردیابی تنظیم نشده، `pending` یعنی هرگز از بررسی سربلند بیرون نیامده، `active` یعنی ایمیل‌های تازه از آن استفاده می‌کنند، و `failed` یعنی پیش‌تر موفق بوده و از آن پس از رده خارج شده است. میزبان فعال پس از سه بررسی ناموفق پیاپی، یا وقتی از آخرین بررسی موفقش بیش از 2 ساعت گذشته باشد، از رده خارج می‌شود.
tracking.activebool- دقیقاً وقتی درست است که `status` برابر `active` باشد، یعنی وقتی پیوندهای ردیابی‌شده و پیکسل بازشدن در نامه‌های تازهٔ آن دامنه از این میزبان استفاده می‌کنند.
tracking.targetstring- نشانی‌ای که رکورد CNAME به آن اشاره می‌کند، تنها برای همین دامنهٔ ردیابی آماده شده. تا وقتی `host` برابر null است، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آماده‌شدن است، رشتهٔ خالی است.
tracking.recordarray or null- رکوردی که باید منتشر شود، یک آرایه با `type` (همیشه `CNAME`)، `name` و `value`، با نامِ `host` و مقدار `target`. وقتی دامنهٔ ردیابی‌ای نیست، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آماده شدن است، null است، پس `$domain['tracking']['record']['value'] ?? null` آن را بی‌خطر می‌خواند.
tracking.checkedAtstring or null- آخرین باری که میزبان بررسی شده، به‌صورت یک رشته با قالب ISO 8601. تا نخستین بررسی null است.
tracking.verifiedAtstring or null- آخرین باری که بررسی‌ای موفق شده، به‌صورت یک رشته با قالب ISO 8601. برای میزبانی که هرگز بررسی‌ای را نگذرانده null است.
tracking.errorstring or null- آنچه آخرین بررسی یافته، با عبارتی که صاحب دامنه بتواند بر اساسش اقدام کند. وقتی آخرین بررسی موفق بوده یا هنوز هیچ بررسی‌ای اجرا نشده null است. میزبانی که در یک یا دو بررسی ناموفق بوده هنوز `active` است و دلیلش را اینجا با خود دارد.
addressesarray- همهٔ ردیف‌های نشانی روی دامنه، که همان چیزی است که `get` نسبت به یک ردیف `list` می‌افزاید. شامل ردیف‌هایی هم هست که خودِ فرایند تحویل زیر catch-all نوشته است، و همان لحظه که catch-all خاموش شود پذیرش آن‌ها متوقف می‌شود، پس این فهرست فهرستِ نشانی‌هایی که ایمیل دریافت خواهند کرد نیست.
addresses[].addressstring- نشانی کامل، که از local-part ذخیره‌شده و نام میزبان بازساخته و به حروف کوچک تبدیل شده است، تا همیشه با `domain` بالا بخواند و از آن فاصله نگیرد.
addresses[].enabledbool- false نشانی را غیرفعال می‌کند، و نشانی غیرفعال حتی وقتی catch-all روشن است هم رد می‌شود. ردیف‌ها در هر حال فهرست می‌شوند، پس به‌جای خواندن فهرست به‌عنوان مجموعهٔ نشانی‌های فعال، بر اساس همین فیلد فیلتر کنید.
createdAtstring- زمانی که ردیف دامنه افزوده شد، به‌صورت یک رشته با قالب ISO 8601. زمان تأیید دامنه نیست: آن `receiving.verifiedAt` است، که می‌تواند null باشد در حالی که این یکی مقدار دارد.