الإعداد

ترفع هذه الحالات ValueError، أو TypeError حيث يذكر الجدول ذلك، قبل إرسال أي طلب، بدلًا من أن تظهر كفشل محيّر عند أول إرسال. وتوضح الرسالة ما الخطأ وما الذي ينبغي تمريره بدلًا منه.

أنشئ العميل مرة واحدة وشاركه. فإنشاء نسخة جديدة لكل طلب يهدر مجمّع الاتصالات والإعدادات دون مقابل، ولا شيء من حالته خاص بمستدعٍ بعينه.

يمكن مشاركة عميل واحد بين خيوط التنفيذ بأمان. ويغلق 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. ويُفحص قبل إرسال الطلب، بالقاعدة نفسها التي يستخدمها المُنشئ، فيؤدي خطأ مطبعي إلى رفع ValueError يذكر api_key= on this call بدلًا من 401 عن بيانات اعتماد عليك البحث عنها بعد ذلك. والاستدعاء المُعاد يحتفظ بالمفتاح الذي أُعطي له.

timeout بالثواني، ويحلّ محل مهلة العميل لذلك الاستدعاء وحده، في كل محاولة من محاولاته.

يرسل client.raw.request طلبًا مع تطبيق بيانات اعتماد العميل وعنوانه الأساسي ومهلته وسياسة إعادة المحاولة لديه، ويعيد 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، إما الرمز نفسه، وإما دالة تعيده، ويجوز أن تكون async في AsyncOpenEmail. تُستدعى الدالة مرة واحدة لكل استدعاء، وتعيد محاولات ذلك الاستدعاء استخدام ما أعادته، فجدّد الرمز داخلها حين يقترب من الانتهاء، ولن تحتاج إلى إعادة بناء العميل أبدًا.

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'])

قبل تغيير حساس، مثل حذف نطاق أو تغيير webhook، تطلب الواجهة البرمجية من رمز الوصول رمز التحقق الذي كان تطبيق الويب سيطلبه من الشخص. ويرفع الاستدعاء OpenEmailApiError قيمة 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)