پیکربندی

این‌ها پیش از فرستادن هر درخواستی ValueError، یا جایی که جدول می‌گوید TypeError، را raise می‌کنند، به‌جای آنکه به‌صورت شکستی گیج‌کننده در نخستین ارسال شما ظاهر شوند. پیام می‌گوید چه چیزی نادرست بوده و به‌جایش چه باید داد.

کلاینت را یک بار بسازید و به اشتراک بگذارید. نمونهٔ تازه برای هر درخواست، بی‌هیچ سودی استخر اتصال‌ها و پیکربندی را دور می‌ریزد، و هیچ‌یک از وضعیت‌های روی آن مخصوص یک فراخوان نیست.

یک کلاینت را می‌توان بی‌خطر میان threadها به اشتراک گذاشت. close() یا پایان یک بلوک with استخر اتصالی را که خود کلاینت باز کرده می‌بندد، و http_client ای که داده‌اید باز می‌ماند تا خودتان آن را ببندید.

برای موردی که در غیر این صورت به ازای هر کلید یک نمونه لازم می‌کرد، مثلاً کاری که از طرف چند فضای کاری ارسال می‌کند، api_key را روی همان فراخوانی بدهید. برای آن درخواست جایگزین سرآیند Authorization می‌شود و چیزی روی کلاینت باقی نمی‌گذارد.

from openemail.types import EmailSend workspace_key = 'oe_live_...' message: EmailSend = {'from': sender, 'to': recipient, 'subject': subject, 'text': text} client.emails.send(message) client.emails.send(message, api_key=workspace_key) client.threads.list(folder='inbox', api_key=workspace_key)client.webhooks.list(api_key=workspace_key)

هر متدی بیرون از temp_mail آن را به‌صورت آرگومان کلیدواژه‌ای، در کنار timeout، می‌گیرد. پیش از فرستادن درخواست و با همان قاعده‌ای که سازنده به کار می‌برد بررسی می‌شود، پس یک غلط تایپی به‌جای 401 دربارهٔ اعتبارنامه‌ای که باید بگردید و پیدایش کنید، یک ValueError را raise می‌کند که api_key= on this call را نام می‌برد. فراخوانی‌ای که دوباره تلاش می‌شود همان کلیدی را نگه می‌دارد که به آن داده شده بود.

timeout بر حسب ثانیه است و فقط برای همان یک فراخوانی، در هر یک از تلاش‌هایش، جای تایم‌اوت کلاینت را می‌گیرد.

client.raw.request درخواستی را با اعتبارنامه، URL پایه، تایم‌اوت و سیاست تلاش دوبارهٔ کلاینت می‌فرستد و JSON تجزیه‌شده را برمی‌گرداند. method، query، body، api_key و timeout را می‌گیرد. یک GET را دوباره تلاش می‌کند و هر چیز دیگری را یک بار می‌فرستد، مگر اینکه repeatable=True بدهید. idempotent=True یک Idempotency-Key می‌افزاید، همان که به‌صورت idempotency_key می‌دهید یا یکی تازه.

result = client.raw.request('/something-new', method='POST', body={'name': 'Invoices'})

create_temp_mail() کلاینتی می‌سازد که هیچ کلید API حمل نمی‌کند، و create_async_temp_mail() همتای ناهمگام آن است. صندوق‌ها را ناشناس می‌سازد، و هر خواندن توکن صندوقی را می‌فرستد که create بازگردانده بود، یا توکن تازه‌تری را که extend بازگرداند، خواه برای هر فراخوانی به‌صورت inbox_token خواه یک بار به‌صورت create_temp_mail(inbox_token=...).

from openemail import create_temp_mail temp_mail = create_temp_mail() inbox = temp_mail.create()messages = temp_mail.list_messages(inbox['id'], inbox_token=inbox['token']) print(messages['items'], messages['expiresAt'])

برنامه‌ای که شخصی با OAuth متصل کرده، مثل یک ابزار خط فرمان یا یک عامل، به‌جای کلید API یک توکن دسترسی دارد. آن را به‌صورت access_token بدهید: یا خودِ توکن، یا تابعی که آن را برمی‌گرداند و روی AsyncOpenEmail می‌تواند async باشد. تابع برای هر فراخوانی یک بار صدا زده می‌شود و تلاش‌های دوبارهٔ همان فراخوانی از چیزی که برگردانده استفاده می‌کنند، پس وقتی توکن نزدیک انقضاست آن را درون تابع تازه کنید تا هرگز لازم نباشد کلاینت را از نو بسازید.

from openemail import OpenEmail client = OpenEmail(access_token=session.fresh_access_token) me = client.me.get() if me['object'] == 'oauth_token':    print(me['clientId'], me['expiresAt'])

پیش از یک تغییر حساس، مثل حذف یک دامنه یا تغییر یک وب‌هوک، API از توکن دسترسی همان کد تأیید هویتی را می‌خواهد که برنامهٔ وب از شخص می‌خواست. فراخوانی یک OpenEmailApiError را raise می‌کند که is_step_up_required آن True است، و چیزی تغییر نکرده است. یک کد بخواهید، کدی را که شخص به شما می‌دهد تأیید کنید، سپس دوباره فراخوانی کنید. از کلید API هرگز خواسته نمی‌شود.

from openemail import OpenEmailApiError try:    client.domains.delete(domain_id)except OpenEmailApiError as error:    if not error.is_step_up_required:        raise     challenge = client.security.begin_step_up()     if challenge['method'] == 'email':        prompt = f'Enter the code we emailed to {challenge.get("sentTo")}: '    else:        prompt = 'Enter the code from your authenticator app, or a backup code: '     client.security.verify_step_up({'code': input(prompt)})    client.domains.delete(domain_id)