دامنه‌ها
`domains.list`، `list_all`، `iterate`، `get` و `update`.
همهٔ متدها
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endدریافت و ارسال دو واقعیت مستقل‌اند و به‌صورت دو Hash بازگردانده می‌شوند. receiving.verified یعنی MX دامنه ایمیلش را به اینجا می‌آورد و چالش مالکیتش منتشر شده است. sending بررسی امضای خروجی را گزارش می‌دهد: status یکی از verified، pending، failed، no_identity یا unknown است، و canSend می‌گوید آیا ارسالی از این دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفیِ قدیمی‌تر از یک روز به‌جای رد شدن، ناشناخته در نظر گرفته می‌شود، پس به‌جای status روی canSend شاخه بزنید، که به شکل domain.dig(:sending, :canSend) خوانده می‌شود.
list یک OpenEmail::Page از دامنه‌ها به ترتیب الفبایی برمی‌گرداند، و list_all همه را در یک Array برمی‌گرداند. iterate آن‌ها را یکی‌یکی به یک بلاک yield می‌کند. بدون بلاک یک Enumerator برمی‌گرداند.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update دامنهٔ ردیابی اختصاصی دامنه را، یعنی زیردامنه‌ای مانند links.acme.com، تنظیم می‌کند، دوباره بررسی می‌کند یا برمی‌دارد، و همان Hashی را برمی‌گرداند که get. tracking در هر خواندن آن را گزارش می‌دهد. تا وقتی بررسی‌ای موفق نشود، tracking.status برابر pending است و پیوندهای ردیابی‌شده و pixel باز شدن همچنان از میزبان پیش‌فرض OpenEmail استفاده می‌کنند. وقتی بررسی‌ای موفق شود، active می‌شود و ایمیل‌های تازهٔ این دامنه برای هر دو از دامنهٔ ردیابی استفاده می‌کنند.
get نشانی‌های روی دامنه را هم فهرست می‌کند. addresses.list فراخوانی مرتبط است: نشانی‌هایی که این کلید می‌تواند در سرآیند From بگذارد، که محدودتر است، هرکدام با یک حکم canSend. یک OpenEmail::AddressBookPage برمی‌گرداند که آن‌ها را به‌جای items در addresses نگه می‌دارد، در کنار domains و unrestricted. list_all آن یک OpenEmail::AddressBook برمی‌گرداند.
app_host فضای نامی از آنِ خودش است، client.app_host. get، set، verify و delete نشانی برنامهٔ وب فضای کاری را می‌خوانند و تغییر می‌دهند، یعنی زیردامنه‌ای مانند mailbox.acme.com روی یکی از این دامنه‌ها یا هر دامنهٔ دیگری که در اختیار فضای کاری است، که افراد فضای کاری آنجا با برند فضای کاری وارد می‌شوند. set رکوردهای DNS را که باید منتشر شوند برمی‌گرداند، در record و، برای دامنه‌ای بیرون از فضای کاری، ownershipRecord. delete، و setی که نشانی‌ای را جایگزین می‌کند، از برنامهٔ OAuth کد تأیید هویت می‌خواهند: تا وقتی کدی نداشته باشد، فراخوانی یک 403 را raise می‌کند که step_up_required? آن true است.
branding آن برند را تنظیم می‌کند. get پیوندهای نشان، لوگو، لوگوی حالت تیره و عکس صفحهٔ ورود، دو قلم و پس‌زمینهٔ ورود را می‌خواند. update قلم‌ها و پس‌زمینه را تغییر می‌دهد، upload_image(variant, data, content_type: nil) یکی از چهار تصویر را بارگذاری می‌کند، و remove_image(variant) یکی را حذف می‌کند. variant یکی از mark، wordmark، wordmark-dark یا login-background است، و OpenEmail::BRAND_IMAGE_VARIANTS آن‌ها را نام می‌برد. data یک String دودویی، یک IO یا یک Pathname است. یک Pathname مانند Pathname("logo.svg")، یک File یا یک فایل بارگذاری‌شده در Rails نوعش را با خود می‌آورد. بایت‌های دیگر به content_type: نیاز دارند، و تصویر بدون نوع با یک 422 invalid_image رد می‌شود. لوگو همان چیزی است که به نشانی برنامهٔ وب و، در طرح پولی، به ایمیل‌هایی که برای فضای کاری فرستاده می‌شوند برند می‌دهد.
پارامترها: domains.get
idStringالزامی- شناسه از `domains.list`، یک UUID که هنگام افزودن دامنه ساخته شده، نه نام میزبان، پس `get("example.com")` چیزی پیدا نمی‌کند. جست‌وجو علاوه بر شناسه به فضای کاری خودِ کلید هم محدود است، پس دامنهٔ فضای کاری دیگر به‌جای 403 یک 404 است که به‌صورت `OpenEmail::NotFoundError` raise می‌شود. شناسهٔ nil یا خالی پیش از فرستادن هر چیزی ArgumentError را raise می‌کند.
پارامترها: domains.update
idStringالزامی- همان domain id که `get` می‌گیرد. scope مورد نیاز آن `domains:write` است.
trackingHostString or nil- زیردامنه‌ای از همان دامنه، حداکثر 512 نویسه، مانند `links.acme.com`. فاصله‌های اضافی حذف و حروف کوچک می‌شوند، و `https://` یا `http://` ابتدایی، مسیر و نقطهٔ انتهایی حذف می‌شوند. مقدار تازه در همان فراخوانی اعتبارسنجی، ذخیره و بررسی می‌شود. مقداری که دامنه از پیش دارد بررسی را دوباره اجرا می‌کند، مگر آنکه بررسی قبلی کمتر از 30 ثانیه پیش بوده باشد. برای برداشتن دامنهٔ ردیابی nil یا یک String خالی بدهید، و برای دست نزدن به آن، این فیلد را ننویسید.
میزبانی که رد شود یک OpenEmail::ApiError را raise می‌کند که در param نام trackingHost را می‌برد: یک 422 invalid_tracking_host برای نامی که قابل استفاده نیست، مثلاً نامی بیرون از دامنه، یک 409 domain_not_verified برای میزبان تازه وقتی receiving.verified برابر false است و رکورد TXT دامنه با نام _openemail-challenge هنوز منتشر نشده، و یک 409 tracking_host_in_use برای نامی که دامنهٔ دیگری از پیش به کار می‌برد، یا وقتی دامنهٔ ردیابی را سرور OpenEmail دیگری مدیریت می‌کند. 422 به‌صورت OpenEmail::ValidationError می‌رسد و هر 409 به‌صورت OpenEmail::ConflictError. کلیدی که به نشانی‌های خاصی محدود است یک 422 capability_unsupported می‌گیرد، چون دامنهٔ ردیابی روی همهٔ نشانی‌های دامنه اعمال می‌شود.
وصله آرگومان‌های کلیدواژه‌ای یا یک Hash است، و فیلدهایش نام‌های camelCase در API را نگه می‌دارند، پس tracking_host: همان‌طور که نوشته شده فرستاده و با یک 422 unknown_parameter رد می‌شود. update همچنین catchAll، storageHost برای دامنهٔ فایل‌ها مانند files.acme.com، و dmarcPolicy را می‌گیرد. همهٔ فیلدها اختیاری‌اند و مرجع متدها هرکدام را پوشش می‌دهد. gem متد update را مانند یک خواندن دوباره امتحان می‌کند، چون تکرار، میزبان را از پیش تنظیم‌شده می‌یابد و حداکثر دوباره بررسی‌اش می‌کند.
پاسخ: یک دامنه (domains.get)
objectString- همیشه رشتهٔ `domain`، هم روی ردیف‌های `list` و هم روی همین یکی.
idString- UUID دامنه. در تمام عمر آن ردیف پایدار است، و تنها دستگیره‌ای است که دیگر فراخوانی‌های دامنه می‌پذیرند.
domainString- نام میزبان خالی، با حروف کوچک: `example.com`. در کل محصول یکتاست، یک مالک برای هر دامنه، پس دو فضای کاری نمی‌توانند هر دو مدعی آن شوند.
receiving.verifiedBoolean- به محض اینکه DNS نشان دهد MX دامنه میزبانی را نام می‌برد که نامه‌اش را به اینجا می‌آورد، و در جایی که ردیف یک توکن چالش دارد، رکورد TXT متناظر `_openemail-challenge` را هم نشان دهد، True می‌شود. MX به‌تنهایی چیزی را ثابت نمی‌کند، چون هر دامنه‌ای که برایش نامه دریافت می‌کنیم همان نام‌های میزبان را منتشر می‌کند؛ توکن به همین دلیل وجود دارد، و به همین دلیل این پرچم همان دروازه‌ای است که تحویل ورودی پیش از پذیرش نامه بررسی می‌کند.
receiving.verifiedAtString or nil- زمان موفق شدن تأیید، به‌صورت یک String با قالب ISO 8601. تا وقتی تأیید نشده nil است، و `verified` دقیقاً از همین ستون مشتق می‌شود، پس این دو هرگز نمی‌توانند با هم ناسازگار باشند.
receiving.catchAllBoolean- اینکه آیا هر local-partی پذیرفته می‌شود یا نه. برای دامنه‌هایی که پس از قاعده شدنِ این افزوده شده‌اند به‌طور پیش‌فرض روشن است. با خاموش بودنش، فقط نشانی‌های نام‌برده روی دامنه پذیرفته می‌شوند و بقیه در زمان SMTP رد می‌شوند، پس فرستنده به‌جای سکوت یک bounce می‌گیرد.
receiving.lastCheckedAtString or nil- آخرین باری که دربارهٔ این دامنه از DNS پرسیده شد. وقتی هرگز از DNS پرسیده نشده nil است، که برای کسی که یک دقیقه پیش دامنه‌ای افزوده، معنایی بسیار متفاوت از شکست دارد. خواندن دامنهٔ تأییدنشده، وقتی آخرین بررسی بیش از 20 ثانیه قدمت داشته باشد، دوباره از DNS می‌پرسد، پس فراخوانی پیاپی `get` یکی از راه‌های منتظر ماندن برای تأیید است، و `verify` بی‌درنگ بررسی می‌کند.
receiving.errorString or nil- چرا آخرین بررسی موفق نشد، با عبارتی که مالک بتواند بر اساس آن اقدام کند: `No MX records yet. DNS changes can take a few minutes to spread.` نمونه‌ای معمول است. به محض موفق شدن بررسی nil می‌شود، و ذخیره می‌شود نه مشتق، تا بارگذاری دوباره و بررسی دوبارهٔ زمان‌بندی‌شده یک چیز بگویند.
sending.statusString- وضعیت امضای خروجی، همان‌طور که آخرین بررسی آن را دید: `verified`، `pending`، `failed`، `no_identity` یا `unknown`. از بررسی ذخیره‌شده خوانده می‌شود، پس `sending.checkedAt` می‌گوید چقدر قدیمی است.
sending.canSendBoolean- اینکه آیا ارسال از این دامنه همین حالا پذیرفته می‌شود یا نه. حکم منفیِ قدیمی‌تر از یک روز به‌جای رد، نامعلوم در نظر گرفته می‌شود، پس این می‌تواند true باشد در حالی که `status` برابر `pending` است. پیش از ارسال روی همین شاخه بزنید: مقدار false یعنی `emails.send` از این دامنه با یک 409 `domain_not_sendable` رد می‌شود.
sending.checkedAtString or nil- آخرین باری که وضعیت امضا بررسی شده، به‌صورت یک String با قالب ISO 8601. وقتی هرگز بررسی نشده nil است، که معنایی بسیار متفاوت از شکست دارد.
sending.errorString or nil- آخرین شکست امضا به‌صورت متن، یا nil به محض موفقیت.
sending.noteString- یکی از پنج جمله، که بر پایهٔ `sending.status` انتخاب می‌شود و می‌گوید آن وضعیت به زبانی که صاحب دامنه بتواند بر اساسش اقدام کند چه معنایی دارد. نثری برای خواندن آدم است، پس به‌جای این، روی `sending.canSend` شاخه بزنید.
trackingHash- دامنهٔ ردیابی اختصاصی این دامنه، هم روی ردیف‌های `list` و هم روی همین یکی، و همان چیزی که `update` تغییرش می‌دهد.
tracking.hostString or nil- دامنهٔ ردیابی، مانند `links.acme.com`، یا nil وقتی چیزی تنظیم نشده باشد.
tracking.statusString- `none` یعنی هیچ دامنهٔ ردیابی تنظیم نشده، `pending` یعنی هرگز از بررسی سربلند بیرون نیامده، `active` یعنی ایمیل‌های تازه از آن استفاده می‌کنند، و `failed` یعنی پیش‌تر موفق بوده و از آن پس از رده خارج شده است. میزبان فعال پس از سه بررسی ناموفق پیاپی، یا وقتی از آخرین بررسی موفقش بیش از 2 ساعت گذشته باشد، از رده خارج می‌شود.
tracking.activeBoolean- دقیقاً وقتی درست است که `status` برابر `active` باشد، یعنی وقتی پیوندهای ردیابی‌شده و پیکسل بازشدن در نامه‌های تازهٔ آن دامنه از این میزبان استفاده می‌کنند.
tracking.targetString- نشانی‌ای که رکورد CNAME به آن اشاره می‌کند، که تنها برای همین دامنهٔ ردیابی آماده شده. تا وقتی `host` برابر nil است، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آماده شدن است، یک String خالی است.
tracking.recordHash or nil- رکوردی که باید منتشر شود، یک Hash با `type` (همیشه `CNAME`)، `name` و `value`، با نامِ `host` و مقدار `target`. وقتی دامنهٔ ردیابی‌ای نیست، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آماده شدن است، nil است، پس `dig(:tracking, :record, :value)` آن را بی‌خطر می‌خواند.
tracking.checkedAtString or nil- آخرین باری که میزبان بررسی شده، به‌صورت یک String با قالب ISO 8601. تا نخستین بررسی nil است.
tracking.verifiedAtString or nil- آخرین باری که بررسی‌ای موفق شده، به‌صورت یک String با قالب ISO 8601. برای میزبانی که هرگز بررسی‌ای را نگذرانده nil است.
tracking.errorString or nil- آنچه آخرین بررسی یافته، با عبارتی که صاحب دامنه بتواند بر اساسش اقدام کند. وقتی آخرین بررسی موفق بوده یا هنوز هیچ بررسی‌ای اجرا نشده nil است. میزبانی که در یک یا دو بررسی ناموفق بوده هنوز `active` است و دلیلش را اینجا با خود دارد.
addressesArray<Hash>- همهٔ ردیف‌های نشانی روی دامنه، که همان چیزی است که `get` نسبت به یک ردیف `list` می‌افزاید. شامل ردیف‌هایی هم هست که خودِ فرایند تحویل زیر catch-all نوشته است، و همان لحظه که catch-all خاموش شود پذیرش آن‌ها متوقف می‌شود، پس این Array فهرستِ نشانی‌هایی که ایمیل دریافت خواهند کرد نیست.
addresses[].addressString- نشانی کامل، که از local-part ذخیره‌شده و نام میزبان بازساخته و به حروف کوچک تبدیل شده است، تا همیشه با `domain` بالا بخواند و از آن فاصله نگیرد.
addresses[].enabledBoolean- false نشانی را غیرفعال می‌کند، و نشانی غیرفعال حتی وقتی catch-all روشن است هم رد می‌شود. ردیف‌ها در هر حال فهرست می‌شوند، پس به‌جای خواندن Array به‌عنوان مجموعهٔ نشانی‌های فعال، بر اساس همین فیلد فیلتر کنید.
createdAtString- زمانی که ردیف دامنه افزوده شد، به‌صورت یک String با قالب ISO 8601. زمان تأیید دامنه نیست: آن `receiving.verifiedAt` است، که می‌تواند nil باشد در حالی که این یکی مقدار دارد.