Ruby

مخاطبان

`contacts.list`، `get`، `create`، `save`، `update`، `set_audiences`، `delete`، `delete_many`، `list_people`، `set_photo`، `remove_photo`، `block`، `unblock`، `list_threads` و `activity`.

همهٔ متدها

usage.rb

page = client.contacts.list(limit: 100)contact = client.contacts.get("[email protected]") saved = client.contacts.create(  email: "[email protected]",  name: "Grace Hopper",  notes: "Met at the compiler workshop") client.contacts.update("[email protected]", notes: nil)client.contacts.set_audiences("[email protected]", audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"])client.contacts.delete("[email protected]") puts page.items.size, page.has_more?, contact[:source], contact[:lastSeenAt], saved[:source]

list مخاطبانی را که تازه‌تر دیده شده‌اند اول برمی‌گرداند، و مخاطبانی را که هرگز به آن‌ها ایمیلی نرفته در انتها. source وقتی auto است که ردیف به این دلیل نوشته شده باشد که عضوی از راه کامپوزر برنامه به آن نشانی پیامی فرستاده است، که ادعایی به‌کلی متفاوت با ذخیره کردن آن توسط کسی است. رسیدن ایمیل از یک نشانی چیزی نمی‌نویسد، و ارسال از راه این API هم همین‌طور.

دفترچه به فضای کاری تعلق دارد نه به یک نفر، پس مخاطبی که هر عضوی ذخیره کند همان مخاطبی است که هر عضو و هر کلید می‌بیند. create مقدار source را manual می‌نویسد و مخاطب را همان لحظهٔ نوشتن در گروه مخاطب پیش‌فرض می‌گذارد. فهرست‌های خودتان را در audienceIds نام ببرید تا در همان فراخوانی به آن‌ها بپیوندد، که به audiences:write هم نیاز دارد، یا مخاطب را بعداً با audiences.add_contact اضافه کنید، که صفحهٔ «گروه‌های مخاطب» پوشش می‌دهد. set_audiences با یک فراخوانی دقیقاً می‌گوید یک مخاطب در کدام فهرست‌ها باشد.

نشانی‌ها با حروف کوچک ذخیره می‌شوند و gem نشانی‌ای را که می‌دهید encode می‌کند، پس [email protected] به ردیف درست می‌رسد. نشانی nil یا خالی پیش از فرستادن هر چیزی ArgumentError را raise می‌کند. نشانی همان هویت است، پس update نمی‌تواند آن را تغییر دهد: جابه‌جا کردن یک مخاطب یعنی یک delete و یک create.

پارامترها: contacts.list

limitInteger: در هر صفحه چند مخاطب برگردد: عددی صحیح از 1 تا 200 با پیش‌فرض 50. نوعش تبدیل می‌شود، پس Stringی مانند `"100"` که از یک query string خوانده شده مشکلی ندارد، و مقدار بیرون از این بازه به‌جای محدود شدن، یک 422 است.
cursorString: مقدار `next_cursor` از صفحهٔ پیشین. هرگز خودتان یکی نسازید: cursorی که مخاطبی را نام ببرد که دیگر وجود ندارد یک 400 `invalid_cursor` است که به‌صورت `OpenEmail::InvalidRequestError` raise می‌شود، یعنی وضعیت صفحه‌بندی شما کهنه است و پیمایش باید بدون cursor از نو آغاز شود.
sourceString: `manual` برای مخاطبانی که کسی عمداً ذخیره کرده، و `auto` برای آن‌هایی که کامپوزر برنامه ثبت کرده است. برای کل دفترچه آن را ننویسید.
qString: در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.

پاسخ: یک مخاطب

contacts.list یک OpenEmail::Page برمی‌گرداند، پس ردیف‌ها روی page.items هستند و پیمایش تا وقتی page.has_more? برابر true است page.next_cursor را دنبال می‌کند. list_all همهٔ ردیف‌ها را به‌صورت یک Array برمی‌گرداند، و iterate آن‌ها را یکی‌یکی yield می‌کند. get، create، update، save و set_audiences هرکدام یک مخاطب را به‌صورت یک Hash با کلیدهای Symbol برمی‌گردانند، همان ردیف به‌علاوهٔ audiences. دفترچهٔ نشانی‌ها بی‌کران است، و به همین دلیل این مسیر صفحه‌بندی می‌کند به‌جای آنکه Arrayی برگرداند که بی‌صدا در 200 متوقف شده باشد.

objectString: همیشه رشتهٔ `contact`، هم روی ردیف‌های فهرست و هم روی `get`.
emailString: آدرس، که هنگام نوشتن با حروف کوچک ذخیره می‌شود تا `[email protected]` و `[email protected]` یک مخاطب باشند، و همان کلیدی که هر متد contacts می‌گیرد، چون هیچ id ای برای مخاطب آشکار نمی‌شود. ردیف‌ها به فضای کاری تعلق دارند نه به عضو یا کلیدی که آن‌ها را نوشته، پس هر عضو و هر کلید روی فضای کاری یک دفترچهٔ نشانی واحد را می‌خواند و می‌نویسد.
nameString or nil: نام نمایشی، یا nil وقتی هرگز نامی برای آن نشانی ثبت نشده باشد. نوشتن خودکار تنها وقتی نامی دارد که سرآیند چیزی جز خودِ نشانی داده باشد، و هرگز نمی‌تواند نامی را که کاربر تایپ کرده بازنویسی کند.
sourceString: `auto` یعنی ردیف به این دلیل نوشته شده که کاربر به آن نشانی ایمیل فرستاده است. `manual` یعنی کسی آن را دستی وارد کرده، که ادعایی به‌کلی متفاوت است، و یک upsert هرگز `manual` را به `auto` تنزل نمی‌دهد. رسیدن ایمیل از یک نشانی عمداً هیچ ردیفی نمی‌نویسد، پس کسی که فقط به شما نوشته اینجا نیست. با این مقدار مانند یک String باز رفتار کنید، چون این ستون متن آزاد با پیش‌فرض `manual` است.
notesString or nil: متن آزادی که کسی دربارهٔ این شخص نوشته، در برنامه یا از راه `update`، و هرگز تولیدشده نیست. وقتی کسی چیزی ننوشته باشد nil است، و `notes: nil` در `update` آن را پاک می‌کند.
lastSeenAtString or nil: یک String با قالب ISO 8601 به وقت UTC، که هر بار عضوی از کامپوزر برنامه به آن نشانی ارسال کند جلو می‌رود، نه وقتی ایمیلی از آن می‌رسد، که چیزی نمی‌نویسد. روی مخاطبی که با `create` ذخیره شده و هرگز به او ایمیلی نرفته nil است، و این‌ها در ترتیب نزولی `lastSeenAt` که این مسیر برمی‌گرداند در انتها می‌آیند.
audiencesArray<Hash>: فقط روی `get`، `create`، `update`، `save` و `set_audiences`، و هرگز روی ردیف‌های فهرست. هر گروه مخاطبی که مخاطب در آن است، از جمله گروه پیش‌فرض، به‌صورت یک Hash با `id`، `name` و `builtin`. `builtin` روی گروهی که هر مخاطبی به آن تعلق دارد `default` است و روی گروهی که کسی ساخته nil، پس به‌جای نام، که هرکسی می‌تواند عوضش کند، روی آن شاخه بزنید.
photoUrlString or nil: جایی که عکس مخاطب از آن ارائه می‌شود، یا nil وقتی مخاطب عکسی ندارد. `set_photo` آن را تنظیم می‌کند و هر بارگذاری URL تازه‌ای می‌گیرد.

تنظیم گروه‌های مخاطبِ یک مخاطب

set_audiences(email, audienceIds: [...]) با یک درخواست دقیقاً می‌گوید یک مخاطب در کدام گروه‌ها باشد. مخاطب به هر گروه فهرست‌شده‌ای که هنوز در آن نیست می‌پیوندد و هر گروه دیگری را ترک می‌کند، و فراخوانی مخاطب را پس از تغییر، همراه با audiences آن، برمی‌گرداند. به audiences:write نیاز دارد، چون عضویت‌ها را می‌نویسد نه خود مخاطب را، و تکرارش چیزی را تغییر نمی‌دهد، پس gem پس از شکست شبکه دوباره امتحانش می‌کند.

گروه مخاطب پیش‌فرض همیشه نگه داشته می‌شود، پس audienceIds: [] مخاطب را تنها در گروه پیش‌فرض باقی می‌گذارد. تا 100 شناسه می‌پذیرد. شناسه‌ای که به هیچ گروه مخاطبی در این فضای کاری اشاره نکند یک 404 audience_not_found است و هیچ چیز تغییر نمی‌کند، و نشانی‌ای که مخاطب نیست یک 404 contact_not_found است. هر دو OpenEmail::NotFoundError را raise می‌کنند.

همهٔ کسانی که در صفحهٔ مخاطبین هستند

list_people کسانی را فهرست می‌کند که صفحهٔ «مخاطبان» در برنامه نشان می‌دهد: مخاطبان ذخیره‌شده و هر نشانی دیده‌شده در ایمیل‌ها، هرکدام با saved، threads و lastAt. list فقط مخاطبان ذخیره‌شده است. یک OpenEmail::PeoplePage برمی‌گرداند، که seen را به items، has_more? و next_cursor می‌افزاید. نشانی‌های دیده‌شده در ایمیل‌ها فقط وقتی می‌آیند که کلید threads:read را هم داشته باشد، و page.seen می‌گوید آمده‌اند یا نه. sort: یکی از recent، name یا threads است، و OpenEmail::PEOPLE_SORTS آن‌ها را نام می‌برد. q: در نام‌ها، نشانی‌ها و یادداشت‌ها جست‌وجو می‌کند، و blocked: true کسانی را نگه می‌دارد که فهرست مسدودی فضای کاری مسدودشان کرده، از جمله قواعد کل دامنه. blockedBy در هر ردیف قاعده را نام می‌برد.

people.rb

page = client.contacts.list_people(sort: "threads", limit: 50) page.items.each do |person|  client.contacts.save(person[:email]) if !person[:saved] && person[:threads].to_i > 5end blocked = client.contacts.list_all_people(blocked: true)puts page.seen, blocked.size

list_all_people همهٔ صفحه‌ها را به‌صورت یک Array برمی‌گرداند، و iterate_people هر شخص را به یک بلاک yield می‌کند، یا بدون بلاک یک Enumerator برمی‌گرداند. هیچ‌کدام seen را گزارش نمی‌کنند، پس برای دانستنش یک صفحه را با list_people بخوانید. cursor مبهم است، پس next_cursor را دقیقاً همان‌طور که آمده، با همان sort:، q: و blocked:، به‌عنوان cursor: پس بدهید.

ذخیره، حذف و عکس‌ها

save(email)، با name: و notes: اختیاری، همان «افزودن به مخاطبان» و «نگه داشتن در مخاطبان» است: نشانی‌ای را که هنوز مخاطب نیست ذخیره می‌کند، نشانی ثبت‌شده از یک ارسال را به‌عنوان ذخیره‌شدهٔ دستی نگه می‌دارد، و نشانی حذف‌شده را برمی‌گرداند. delete همان «حذف» است: مخاطب ذخیره‌شده را برمی‌دارد و نشانی را پنهان می‌کند تا کامپوزر دوباره ثبتش نکند، و نشانی‌ای را هم که فقط در ایمیل‌ها دیده شده می‌پذیرد. wasSaved در Hashی که برمی‌گرداند می‌گوید کدام بوده است. delete_many در یک فراخوانی تا 200 مورد را حذف می‌کند.

photo.rb

client.contacts.save("[email protected]", name: "Grace Hopper") contact = client.contacts.set_photo("[email protected]", File.binread("photo.jpg"), content_type: "image/jpeg")puts contact[:photoUrl] client.contacts.set_photo("[email protected]", Pathname("photo.png")) client.contacts.remove_photo("[email protected]")client.contacts.delete_many(["[email protected]", "[email protected]"])

set_photo بایت‌های تصویر را همان‌طور که هستند می‌فرستد: PNG، JPEG، WebP یا GIF تا 5 MB، که در مربعی 512 پیکسلی جا داده می‌شود. بایت‌ها یک String دودویی، یک IO یا یک Pathname هستند. content_type: را بدهید، یا بایت‌هایی که نوع خودشان را همراه دارند: شیئی که به content_type پاسخ دهد، مانند یک فایل بارگذاری‌شده در Rails، یا یک File یا Pathname که نامش به .png، .jpg، .jpeg، .webp یا .gif ختم شود. بدون نوع، بایت‌ها به‌صورت application/octet-stream می‌روند، که سرور آن را با یک 422 invalid_image رد می‌کند. OpenEmail::CONTACT_PHOTO_TYPES این چهار نوع را نام می‌برد. نشانی باید پیش از آن مخاطب ذخیره‌شده باشد.

مسدود کردن

block(email) نشانی را در فهرست مسدودی فضای کاری می‌گذارد تا نامه‌اش رد شود و هر برچسب بعلاوه را کنار می‌گذارد، و unblock(email) هر قاعده‌ای را که مسدودش می‌کند برمی‌دارد. هر دو به settings:write نیاز دارند، چون فهرست مسدودی را تغییر می‌دهند نه مخاطب را، و هیچ‌کدام لازم ندارند نشانی مخاطب باشد.

وقتی unblock قاعدهٔ کل دامنه‌ای را برمی‌دارد، removed آن را با list برابر blockedDomains فهرست می‌کند، و مسدودیت همهٔ کسانی که در آن دامنه‌اند همراه آن برداشته می‌شود. OpenEmail::CONTACT_BLOCK_LISTS هر دو فهرست را نام می‌برد.

گفت‌وگوها و فعالیت

list_threads(email) رشته‌هایی را که نشانی نوشته یا به آن نوشته شده، در همهٔ پوشه‌ها، صفحه به صفحه مرور می‌کند، و list_all_threads و iterate_threads همه را می‌پیمایند. activity(email) عددهای پشت زبانهٔ «فعالیت» یک مخاطب را برمی‌گرداند: دریافتی و ارسالی در هر بازه، رشته‌هایی که منتظر پاسخ شما هستند، و میانهٔ زمان پاسخ در هر دو سو. هر دو به threads:read نیاز دارند.

activity.rb

threads = client.contacts.list_threads("[email protected]", q: "invoice") activity = client.contacts.activity(  "[email protected]",  minutes: 30 * 24 * 60,  grain: "day",  offset_minutes: Time.now.utc_offset / 60) puts threads.items.size, activity.dig(:totals, :waiting)

activity کلیدواژه‌های snake_case می‌گیرد. minutes: پنجره را تعیین می‌کند، که اگر داده نشود 90 روز است. grain: پهنای هر بازه را تعیین می‌کند: minute، hour یا day. offset_minutes: تعداد دقیقه‌های شرق UTC را تعیین می‌کند که مرز روزها بر اساس آن است. Time.now.utc_offset / 60 همان offset محلی است، و gem آن را به‌عنوان offsetMinutes در API می‌فرستد.