SDK

دامنه‌ها

`domains.list`، `get` و `update`.

همهٔ متدها

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

دریافت و ارسال دو واقعیت مستقل‌اند و به‌صورت دو شیء بازگردانده می‌شوند. receiving.verified یعنی MX دامنه ایمیلش را به اینجا می‌آورد و چالش مالکیتش منتشر شده است. sending بررسی امضای خروجی را گزارش می‌دهد: status یکی از verified، pending، failed، no_identity یا unknown است، و canSend می‌گوید آیا ارسالی از آن دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفی‌ای که بیش از یک روز از آن گذشته باشد به‌جای رد، ناشناخته در نظر گرفته می‌شود، پس به‌جای status روی canSend شاخه بزنید.

update دامنهٔ ردیابی اختصاصی دامنه را تنظیم می‌کند، دوباره بررسی می‌کند یا برمی‌دارد، یعنی زیردامنه‌ای مانند links.acme.com، و به همان DomainDetailResource ای می‌رسد که get می‌رسد. tracking در هر خواندن آن را گزارش می‌دهد. تا وقتی بررسی‌ای موفق نشود، tracking.status برابر pending است و پیوندهای ردیابی‌شده و پیکسل بازشدن همچنان از میزبان پیش‌فرض OpenEmail استفاده می‌کنند. به‌محض موفقیت یکی، مقدار active می‌شود و ایمیل‌های تازهٔ آن دامنه برای هر دو از دامنهٔ ردیابی استفاده می‌کنند.

get آدرس‌های روی دامنه را هم فهرست می‌کند. addresses.list() فراخوانی مرتبط است: هر آدرسی که این کلید می‌تواند در سرآیند From بگذارد، که محدودتر است.

پارامترها: domains.get

domainIdstringالزامی: id از `domains.list`، یک UUID که هنگام افزودن دامنه ساخته شده، نه نام میزبان، پس `get('example.com')` چیزی پیدا نمی‌کند. جست‌وجو علاوه بر id به connection خود کلید نیز محدود است، پس دامنهٔ فضای کاری دیگر به‌جای 403 یک 404 است.

پارامترها: domains.update

idstringالزامی: همان domain id که `get` می‌گیرد. scope مورد نیاز آن `domains:write` است.
patch.trackingHoststring | nullالزامی: زیردامنه‌ای از همان دامنه، حداکثر 512 نویسه، مانند `links.acme.com`. فاصله‌های اضافی حذف و حروف کوچک می‌شوند، و `https://` یا `http://` ابتدایی، مسیر و نقطهٔ انتهای نام حذف می‌شوند. مقدار تازه در همان فراخوانی اعتبارسنجی، ذخیره و بررسی می‌شود. اگر همان مقداری باشد که دامنه از پیش دارد، بررسی دوباره اجرا می‌شود، مگر آنکه از آخرین بررسی کمتر از 30 ثانیه گذشته باشد. `null` یا رشتهٔ خالی دامنهٔ ردیابی را برمی‌دارد.

میزبان ردشده یک OpenEmailApiError پرتاب می‌کند که در param نام trackingHost را می‌برد: 422 invalid_tracking_host برای نامی که قابل استفاده نیست، مثلاً نامی بیرون از دامنه؛ 409 domain_not_verified برای میزبان تازه وقتی receiving.verified نادرست است و رکورد TXT با نام _openemail-challenge دامنه هنوز منتشر نشده؛ و 409 tracking_host_in_use برای نامی که دامنهٔ دیگری از پیش به کار می‌برد، یا وقتی دامنهٔ ردیابی را سرور OpenEmail دیگری مدیریت می‌کند. کلیدی که به آدرس‌های مشخصی محدود شده 422 capability_unsupported می‌گیرد، چون دامنهٔ ردیابی روی همهٔ آدرس‌های آن دامنه اعمال می‌شود.

پاسخ: DomainDetailResource

object'domain': همیشه رشتهٔ `domain`، هم روی ردیف‌های `list` و هم روی همین یکی.
idstring: UUID دامنه. در تمام عمر آن ردیف پایدار است، و تنها دستگیره‌ای است که دیگر فراخوانی‌های domain می‌پذیرند.
domainstring: نام میزبان خالی، با حروف کوچک: `example.com`. در کل محصول یکتاست، یک مالک برای هر دامنه، پس دو فضای کاری نمی‌توانند هر دو مدعی آن شوند.
receiving.verifiedboolean: به محض اینکه DNS نشان دهد MX دامنه میزبانی را نام می‌برد که نامه‌اش را به اینجا می‌آورد — و در جایی که ردیف یک توکن چالش دارد، رکورد TXT متناظر `_openemail-challenge` را هم نشان دهد — True می‌شود. MX به‌تنهایی چیزی را ثابت نمی‌کند، چون هر دامنه‌ای که برایش نامه دریافت می‌کنیم همان نام‌های میزبان را منتشر می‌کند؛ توکن به همین دلیل وجود دارد، و به همین دلیل این پرچم همان دروازه‌ای است که تحویل ورودی پیش از پذیرش نامه بررسی می‌کند.
receiving.verifiedAtstring | null: زمان موفق‌شدن تأیید، به شکل ISO-8601. تا وقتی تأیید نشده Null است، و `verified` دقیقاً از همین ستون مشتق می‌شود، پس این دو هرگز نمی‌توانند با هم ناسازگار باشند.
receiving.catchAllboolean: اینکه آیا هر local-part پذیرفته می‌شود یا نه. برای دامنه‌هایی که پس از قاعده‌شدنِ این افزوده شده‌اند به‌صورت پیش‌فرض روشن است؛ با خاموش بودنش فقط نشانی‌های نام‌برده روی دامنه پذیرفته می‌شوند و بقیه در زمان SMTP رد می‌شوند، پس فرستنده به‌جای سکوت یک bounce می‌گیرد.
receiving.lastCheckedAtstring | null: آخرین باری که دربارهٔ این دامنه از DNS پرسیده شد. Null یعنی هرگز نگاه نشده، که برای کسی که یک دقیقه پیش دامنه‌ای افزوده معنایی بسیار متفاوت از شکست دارد. این endpoint نتیجهٔ ذخیره‌شده را گزارش می‌کند و هرگز خودش بررسی‌ای اجرا نمی‌کند.
receiving.errorstring | null: چرا آخرین بررسی موفق نشد، با عبارتی که مالک بتواند بر اساس آن اقدام کند: `No MX records yet. DNS changes can take a few minutes to spread.` نمونه‌ای معمول است. به محض موفق شدن Null می‌شود، و ذخیره می‌شود نه مشتق، تا بارگذاری دوباره و بررسی مجدد زمان‌بندی‌شده یک چیز بگویند.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': وضعیت امضای خروجی، همان‌طور که آخرین بررسی آن را دید. از بررسی ذخیره‌شده خوانده می‌شود نه با کاوش در همین درخواست، پس `sending.checkedAt` می‌گوید چقدر قدیمی است.
sending.canSendboolean: اینکه آیا ارسال از این دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفیِ قدیمی‌تر از یک روز به‌جای رد، نامعلوم در نظر گرفته می‌شود، پس این می‌تواند true باشد در حالی که `status` برابر `pending` است. پیش از ارسال روی همین شاخه بزنید: مقدار false یعنی `emails.send` از این دامنه با یک 409 `domain_not_sendable` رد می‌شود.
sending.checkedAtstring | null: آخرین باری که وضعیت امضا بررسی شده، به‌صورت ISO-8601. null یعنی هرگز، که خوانشی بسیار متفاوت از شکست دارد.
sending.errorstring | null: آخرین شکست امضا به‌صورت متن، یا null به‌محض موفقیت.
sending.notestring: یکی از پنج جمله، که بر پایهٔ `sending.status` انتخاب می‌شود و می‌گوید آن وضعیت به زبانی که صاحب دامنه بتواند بر اساسش اقدام کند چه معنایی دارد. نثری برای خواندن انسان. به‌جای این، روی `sending.canSend` شاخه بزنید.
trackingDomainTracking: دامنهٔ ردیابی اختصاصی این دامنه، هم روی ردیف‌های `list` و هم روی همین یکی، و همان چیزی که `update` تغییرش می‌دهد.
tracking.hoststring | null: دامنهٔ ردیابی، مانند `links.acme.com`، یا null وقتی چیزی تنظیم نشده باشد.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` یعنی هیچ دامنهٔ ردیابی تنظیم نشده، `pending` یعنی هرگز از بررسی سربلند بیرون نیامده، `active` یعنی ایمیل‌های تازه از آن استفاده می‌کنند، و `failed` یعنی پیش‌تر موفق بوده و از آن پس از رده خارج شده است. میزبان فعال پس از سه بررسی ناموفق پیاپی، یا وقتی از آخرین بررسی موفقش بیش از 2 ساعت گذشته باشد، از رده خارج می‌شود.
tracking.activeboolean: دقیقاً وقتی درست است که `status` برابر `active` باشد، یعنی وقتی پیوندهای ردیابی‌شده و پیکسل بازشدن در ایمیل‌های تازهٔ آن دامنه از این میزبان استفاده می‌کنند.
tracking.targetstring: نشانی‌ای که رکورد CNAME به آن اشاره می‌کند، که تنها برای همین دامنهٔ ردیابی آماده شده است. تا وقتی `host` برابر null است، و تا وقتی نشانی میزبان تازه هنوز در حال آماده‌سازی است، رشتهٔ خالی است.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: رکوردی که باید منتشر شود، با نامی برگرفته از `host` و مقدار `target`. وقتی دامنهٔ ردیابی وجود ندارد، و تا وقتی نشانی میزبان تازه هنوز در حال آماده‌سازی است، null است.
tracking.checkedAtstring | null: آخرین باری که میزبان بررسی شده، به‌صورت ISO-8601. تا نخستین بررسی null است.
tracking.verifiedAtstring | null: آخرین باری که یک بررسی موفق شد، به شکل ISO-8601. برای میزبانی که هرگز بررسی‌ای را با موفقیت نگذرانده Null است.
tracking.errorstring | null: آنچه آخرین بررسی یافت، با عبارتی که مالک دامنه بتواند بر اساس آن اقدام کند. وقتی آخرین بررسی موفق بوده یا هنوز هیچ بررسی‌ای اجرا نشده، Null است. میزبانی که یک یا دو بررسی را رد کرده هنوز `active` است و دلیل را همین‌جا حمل می‌کند.
addressesArray<{ address: string; enabled: boolean }>: همهٔ ردیف‌های نشانی روی دامنه؛ همین است آنچه `get` نسبت به یک ردیف `list` اضافه می‌کند. شامل ردیف‌هایی هم هست که خودِ تحویل زیر catch-all نوشته است، و همان لحظه که catch-all خاموش شود پذیرش آن‌ها متوقف می‌شود، پس این آرایه فهرستِ آنچه نامه دریافت خواهد کرد نیست.
addresses[].addressstring: نشانی کامل، که از local-part ذخیره‌شده و نام میزبان بازساخته و به حروف کوچک تبدیل شده است، تا همیشه با `domain` بالا بخواند و از آن فاصله نگیرد.
addresses[].enabledboolean: False نشانی را غیرفعال می‌کند، و نشانی غیرفعال حتی وقتی catch-all روشن است هم رد می‌شود. ردیف‌ها در هر حال فهرست می‌شوند، پس به‌جای خواندن آرایه به‌عنوان مجموعهٔ نشانی‌های کارا، روی همین فیلد فیلتر کنید.
createdAtstring: زمانی که ردیف دامنه افزوده شد، به شکل ISO-8601. نه زمان تأیید آن: آن `receiving.verifiedAt` است که می‌تواند null باشد در حالی که این یکی مقدار دارد.