مخاطبان
`contacts.list`، `get`، `create`، `save`، `update`، `set_audiences`، `delete`، `delete_many`، `list_people`، `set_photo`، `remove_photo`، `block`، `unblock`، `list_threads` و `activity`.
همهٔ متدها
from openemail import openemail page = openemail.contacts.list(limit=100)contact = openemail.contacts.get('[email protected]') saved = openemail.contacts.create({ 'email': '[email protected]', 'name': 'Grace Hopper', 'notes': 'Met at the compiler workshop',}) openemail.contacts.update(saved['email'], {'notes': None})openemail.contacts.set_audiences(saved['email'], { 'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],})openemail.contacts.delete(saved['email']) print(len(page['items']), page['hasMore'], contact['source'], contact['lastSeenAt'])تازه‌ترین دیده‌شده در ابتدا، و مخاطبانی که هرگز به آن‌ها ایمیلی نرفته در انتها. source وقتی auto است که ردیف به این دلیل نوشته شده باشد که عضوی از راه نویسندهٔ برنامه به آن آدرس پیامی فرستاده است، که ادعایی به‌کلی متفاوت با ذخیره‌کردن دستی آن توسط کسی است. رسیدن ایمیل از یک آدرس چیزی نمی‌نویسد، و ارسال از راه این API هم همین‌طور.
دفترچه به فضای کاری تعلق دارد نه به یک نفر، پس مخاطبی که هر عضوی ذخیره کند همان مخاطبی است که هر عضو و هر کلید می‌بیند. create مقدار source را manual می‌نویسد و مخاطب را همان لحظهٔ نوشتن در audience پیش‌فرض می‌گذارد. فهرست‌های خودتان را در audienceIds نام ببرید تا در همان فراخوانی به آن‌ها بپیوندد، که به audiences:write هم نیاز دارد، یا مخاطب را بعداً با openemail.audiences.add_contact اضافه کنید. set_audiences با یک فراخوانی دقیقاً می‌گوید یک مخاطب در کدام فهرست‌ها باشد.
آدرس‌ها با حروف کوچک ذخیره می‌شوند و کلاینت آدرسی را که می‌دهید encode می‌کند، پس [email protected] به ردیف درست می‌رسد. آدرس همان هویت است، پس update نمی‌تواند آن را تغییر دهد: جابه‌جاکردن یک مخاطب یعنی یک delete و یک create.
پارامترها: contacts.list
limitint- در هر صفحه چند مخاطب برگردد: عددی صحیح از 1 تا 200 با پیش‌فرض 50. مقدار تبدیل نوع می‌شود، پس `'100'` که از یک رشتهٔ پرس‌وجو می‌آید مشکلی ندارد، و مقدار بیرون از این بازه به‌جای محدودشدن، 422 است.
cursorstr- مقدار `nextCursor` از صفحهٔ پیشین. هرگز خودتان یکی نسازید: cursor ای که مخاطبی را نام ببرد که دیگر وجود ندارد 400 `invalid_cursor` است، یعنی وضعیت صفحه‌بندی شما کهنه است و پیمایش باید بدون cursor از نو آغاز شود.
sourceContactSource- `'manual'` برای مخاطبانی که کسی عمداً ذخیره کرده، و `'auto'` برای آن‌هایی که نویسندهٔ برنامه ثبت کرده است. برای کل دفترچه آن را ندهید.
qstr- در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.
پاسخ: ContactResource
contacts.list یک Page[ContactResource] برمی‌گرداند، پس ردیف‌ها روی page['items'] هستند و پیمایش تا وقتی page['hasMore'] برابر True است page['nextCursor'] را دنبال می‌کند، کاری که list_all و iterate برایتان انجام می‌دهند. get، create، save، update، set_audiences، set_photo و remove_photo هرکدام یک ContactDetailResource برمی‌گردانند، همان ردیف به‌علاوهٔ audiences. دفترچهٔ نشانی‌ها بی‌کران است، و به همین دلیل این مسیر صفحه‌بندی می‌کند به‌جای آنکه فهرستی بازگرداند که بی‌صدا در 200 ردیف متوقف شده است.
objectLiteral['contact']- همیشه رشتهٔ `contact`، هم روی ردیف‌های فهرست و هم روی `get`.
emailstr- آدرس، که هنگام نوشتن با حروف کوچک ذخیره می‌شود تا `[email protected]` و `[email protected]` یک مخاطب باشند، و همان کلیدی که هر متد contacts می‌گیرد، چون هیچ id ای برای مخاطب آشکار نمی‌شود. ردیف‌ها به فضای کاری تعلق دارند نه به عضو یا کلیدی که آن‌ها را نوشته، پس هر عضو و هر کلید روی فضای کاری یک دفترچهٔ نشانی واحد را می‌خواند و می‌نویسد.
namestr | None- وقتی هرگز نامی برای آن نشانی ثبت نشده باشد `None` است. نوشتن خودکار تنها وقتی نامی را حمل می‌کند که سرآیند چیزی جز خود نشانی داده باشد، و هرگز نمی‌تواند نامی را که کاربر تایپ کرده بازنویسی کند.
sourceContactSource | str- `auto` یعنی ردیف به این دلیل نوشته شده که کاربر به آن آدرس ایمیل فرستاده است؛ `manual` یعنی کسی آن را دستی وارد کرده، که ادعایی به‌کلی متفاوت است، و یک upsert هرگز `manual` را به `auto` تنزل نمی‌دهد. رسیدن ایمیل از یک آدرس عمداً هیچ ردیفی نمی‌نویسد، پس کسی که فقط به شما نوشته اینجا نیست؛ این union باز می‌ماند چون این ستون متن آزاد با پیش‌فرض `manual` است.
notesstr | None- متن آزادی که کسی دربارهٔ این شخص نوشته، در برنامه یا از راه `update`، و هرگز تولیدشده نیست. وقتی کسی چیزی ننوشته باشد `None` است، و `None` صریح در `update` آن را پاک می‌کند.
lastSeenAtstr | None- ISO-8601 به وقت UTC، که هر بار عضوی از نویسندهٔ برنامه به آن نشانی ارسال کند جلو می‌رود، نه وقتی ایمیلی از آن می‌رسد که چیزی نمی‌نویسد. روی مخاطبی که با `create` ذخیره شده و هرگز به او ایمیلی نرفته `None` است، و این‌ها در ترتیب نزولی `lastSeenAt` که این مسیر برمی‌گرداند در انتها می‌آیند.
audienceslist[ContactAudienceResource]- فقط روی `get`، `create`، `save`، `update`، `set_audiences`، `set_photo` و `remove_photo`، و هرگز روی ردیف‌های فهرست. هر گروه مخاطبی که مخاطب در آن است، به شکل دیکشنری‌ای با `id`، `name` و `builtin`، از جمله گروه پیش‌فرض. `builtin` روی گروهی که هر مخاطبی به آن تعلق دارد `default` است و روی گروهی که کسی ساخته `None`، پس به‌جای نام که هرکسی می‌تواند عوضش کند، روی آن شاخه بزنید.
photoUrlstr | None- جایی که عکس مخاطب از آن ارائه می‌شود، یا `None` وقتی مخاطب عکسی ندارد. `set_photo` آن را می‌گذارد و هر بارگذاری URL تازه‌ای می‌گیرد.
تعیین گروه‌های مخاطب یک مخاطب
set_audiences(email, {'audienceIds': [...]}) با یک درخواست دقیقاً می‌گوید یک مخاطب در کدام گروه‌ها باشد. مخاطب به هر گروه فهرست‌شده‌ای که هنوز در آن نیست می‌پیوندد و هر گروه دیگری را ترک می‌کند، و فراخوانی ContactDetailResource را پس از تغییر برمی‌گرداند. به audiences:write نیاز دارد، چون عضویت‌ها را می‌نویسد نه خود مخاطب را، و تکرارش چیزی را تغییر نمی‌دهد.
گروه مخاطبان پیش‌فرض همیشه نگه داشته می‌شود، پس {'audienceIds': []} مخاطب را تنها در گروه مخاطبان پیش‌فرض باقی می‌گذارد. تا ۱۰۰ شناسه می‌پذیرد. شناسه‌ای که به هیچ گروه مخاطبی در این فضای کاری اشاره نمی‌کند 404 audience_not_found می‌دهد و هیچ چیز تغییر نمی‌کند، و نشانی‌ای که مخاطب نیست 404 contact_not_found می‌دهد.
همهٔ کسانی که در صفحهٔ مخاطبین هستند
list_people کسانی را فهرست می‌کند که صفحهٔ مخاطبین برنامه نشان می‌دهد: مخاطبان ذخیره‌شده و هر نشانی دیده‌شده در نامه‌ها، هرکدام با saved، threads و lastAt. list فقط مخاطبان ذخیره‌شده است. نشانی‌های دیده‌شده در نامه‌ها فقط وقتی می‌آیند که کلید threads:read را هم داشته باشد، و page['seen'] می‌گوید آمده‌اند یا نه. sort یکی از recent، name یا threads است، q در نام‌ها، نشانی‌ها و یادداشت‌ها جست‌وجو می‌کند، و blocked=True فقط کسانی را نگه می‌دارد که فهرست مسدودی فضای کاری مسدودشان کرده است، از جمله قاعده‌های کل دامنه. blockedBy در هر ردیف قاعده را نام می‌برد.
from openemail import openemail page = openemail.contacts.list_people(sort='threads', limit=50) for person in page['items']: if not person['saved'] and (person['threads'] or 0) > 5: openemail.contacts.save(person['email']) blocked = openemail.contacts.list_all_people(blocked=True)list_all_people و iterate_people همهٔ صفحه‌ها را می‌پیمایند. نشانگر مات است، پس nextCursor را همان‌طور که آمد، با همان sort، q و blocked برگردانید.
ذخیره، حذف و عکس‌ها
save(email, {'name': ..., 'notes': ...}) همان افزودن به مخاطبان و نگه‌داشتن در مخاطبان است: نشانی‌ای را که هنوز مخاطب نیست ذخیره می‌کند، نشانی ثبت‌شده از یک ارسال را به‌عنوان ذخیره‌شدهٔ دستی نگه می‌دارد و نشانی حذف‌شده را برمی‌گرداند. delete همان حذف است: مخاطب ذخیره‌شده را برمی‌دارد و نشانی را پنهان می‌کند تا نویسنده دوباره ثبتش نکند، و نشانی‌ای را هم که فقط در نامه‌ها دیده شده می‌پذیرد. wasSaved می‌گوید کدام بوده است. delete_many در یک فراخوانی تا ۲۰۰ مورد را حذف می‌کند.
from pathlib import Path from openemail import openemail openemail.contacts.save('[email protected]', {'name': 'Grace Hopper'}) photo = Path('grace.jpg').read_bytes()contact = openemail.contacts.set_photo('[email protected]', photo, content_type='image/jpeg') openemail.contacts.remove_photo('[email protected]')openemail.contacts.delete_many(['[email protected]', '[email protected]'])set_photo بایت‌های تصویر را همان‌طور که هستند می‌فرستد: PNG، JPEG، WebP یا GIF تا 5 MB، جاداده در مربعی 512 پیکسلی. content_type= را بدهید، چون بایت‌ها نوعی از خودشان ندارند: بدون آن، بارگذاری به شکل application/octet-stream می‌رود که با 422 invalid_image رد می‌شود. نشانی باید پیش از آن مخاطب ذخیره‌شده باشد.
مسدود کردن
block(email) نشانی را در فهرست مسدودی فضای کاری می‌گذارد تا نامه‌اش رد شود و هر برچسب بعلاوه را کنار می‌گذارد، و unblock(email) هر قاعده‌ای را که مسدودش می‌کند برمی‌دارد. هر دو به settings:write نیاز دارند، چون فهرست مسدودی را تغییر می‌دهند نه مخاطب را، و هیچ‌کدام لازم ندارند نشانی مخاطب باشد.
وقتی unblock قاعدهٔ کل دامنه‌ای را برمی‌دارد، removed آن را با list برابر blockedDomains فهرست می‌کند، و مسدودیت همهٔ کسانی که در آن دامنه‌اند همراه آن برداشته می‌شود.
گفت‌وگوها و فعالیت
list_threads(email) رشته‌هایی را که نشانی نوشته یا به آن نوشته شده است، در همهٔ پوشه‌ها، صفحه به صفحه ورق می‌زند، و list_all_threads و iterate_threads همه را می‌پیمایند. activity(email) عددهای پشت زبانهٔ فعالیت یک مخاطب را برمی‌گرداند: دریافتی و ارسالی برای هر بازهٔ کوچک، رشته‌هایی که منتظر پاسخ شما هستند، و میانهٔ زمان پاسخ در هر دو سو. هر دو به threads:read نیاز دارند.
import time from openemail import openemail threads = openemail.contacts.list_threads('[email protected]', q='invoice') activity = openemail.contacts.activity( '[email protected]', minutes=30 * 24 * 60, grain='day', offset_minutes=time.localtime().tm_gmtoff // 60,) print(len(threads['items']), activity['totals']['waiting'])مرجع
contacts.list()مرجع کاملcontacts.list_all()مرجع کاملcontacts.iterate()مرجع کاملcontacts.get()مرجع کاملcontacts.create()مرجع کاملcontacts.save()مرجع کاملcontacts.update()مرجع کاملcontacts.set_audiences()مرجع کاملcontacts.delete()مرجع کاملcontacts.delete_many()مرجع کاملcontacts.list_people()مرجع کاملcontacts.list_all_people()مرجع کاملcontacts.iterate_people()مرجع کاملcontacts.set_photo()مرجع کاملcontacts.remove_photo()مرجع کاملcontacts.block()مرجع کاملcontacts.unblock()مرجع کاملcontacts.list_threads()مرجع کاملcontacts.list_all_threads()مرجع کاملcontacts.iterate_threads()مرجع کاملcontacts.activity()مرجع کامل