Java
الأدوات المساعدة والثوابت
ما تعرّفه الحزمة غير توابع العميل.
التوابع الساكنة
| الطريقة | ما هي |
|---|---|
| new OpenEmail(), OpenEmail.builder() | عميل. كلاهما يقرأ البيئة لكل ما تتركه. |
| OpenEmail.createTempMail() | عميل لصناديق البريد المؤقتة لا يحمل أي مفتاح API. |
| OpenEmail.verifyWebhookSignature() | تتحقق من توقيع تسليم في زمن ثابت، مع نافذة من خمس دقائق تغيّرها Duration، وتعيد الحدث. |
| OpenEmail.toBase64() | نص base64 لبايتات مرفق. |
| OpenEmail.isApiKey() | ما إذا كانت القيمة تحمل شكل oe_live_ أو oe_test_. وهو فحص شكل، لا دليل على أن المفتاح ما زال يعمل. |
| OpenEmail.isAccessToken() | ما إذا كانت القيمة تحمل شكل رمز وصول OAuth: من 1 إلى 512 حرفًا، ولا تبدأ بـ oe_. |
| OpenEmail.isSealed() | ما إذا كان متن الرسالة نصًا مشفَّرًا. وتكون القيمة false للصيغتين الموقَّعتين اللتين وصل متنهما مكشوفًا. |
| OpenEmail.resolveLanguage(), OpenEmail.languageByCode(), OpenEmail.isRtlLanguage() | عمليات البحث التي يحتاجها منتقي اللغات، على الجدول المضمَّن Languages.ALL. |
| client.raw().request() | تستدعي مسارًا لا تغلفه أي دالة بعد، ببيانات اعتماد العميل وسياسة إعادة المحاولة لديه. |
الثوابت
كل مجموعة قيم يصدّرها TypeScript SDK هي صنف نهائي في uk.openemail.constants، فيه ثابت لكل عضو بالأسماء نفسها، لذا فإن WebhookEvents.EMAIL_DELIVERED هو email.delivered. تعيد values() المجموعة كلها، وهذه أيضًا طريقة التحقق من قيمة جاءت من الخارج.
List<String> events = WebhookEvents.values();List<String> scopes = List.of(ApiScopes.EMAILS_SEND, ApiScopes.THREADS_READ);boolean known = events.contains("email.delivered"); System.out.println(events.size() + " " + String.join(",", scopes) + " " + PageLimits.MAX_LIMIT + " " + known);| الثابت | ما يحتويه |
|---|---|
| OpenEmail.VERSION | إصدار الحزمة. |
| ApiScopes | مفردات النطاقات، من أجل شاشة إنشاء مفتاح. |
| WebhookEvents, WebhookSignatureHeaders | الأحداث التي يمكن لنقطة نهاية الاشتراك فيها، وأسماء الترويسات التي يحملها التسليم. |
| ErrorTypes | مفردات الأخطاء التي تعيدها ApiException.type(). |
| PageLimits | أكبر قيمة لـ limit وقيمته الافتراضية في معظم القوائم المقسّمة إلى صفحات، MAX_LIMIT وDEFAULT_LIMIT: 100 و25. بعض القوائم تقبل أكثر، ومرجع كل دالة يذكر ذلك. |
| RuleFields, RuleOperators, RuleActions | المفردات التي تُبنى منها شروط القاعدة وإجراءاتها. |
| MessageEncryptionFormats | الأغلفة الخمسة التي يمكن للاستقبال تسميتها. ثلاثة منها مختومة. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | أي بيانات اعتماد تصفها me().get وme().ping، وكيف يُتحقق من رمز التحقق، والرموز التي قد يفشل بها التحقق. |
| ThreadSorts وPeopleSorts وFileSorts وسائر *Sorts | الترتيبات التي يمكن ترتيب القائمة بها. |
| FormStatuses وBroadcastStatuses وSuppressionReasons وسائر المجموعات | القيم التي يمكن أن يأخذها حقل في مورد. وكل مجموعة مسمّاة باسم ما تحمله. |
| Languages.ALL | كل لغة يقبلها الإرسال المترجَم أو المعاينة، مع رمزها وأسمائها واتجاهها. |
الكائنات
الاستجابة هي JSON بعد فك ترميزه على هيئة Map<String, Object>. لا تبني الحزمة نوعًا خاصًا بها إلا حيث تعيد تشكيل الجواب. كل منها record غير قابل للتغيير في uk.openemail.result، وحلقة for تمر على صفوفه.
| الصنف | ما يحمله |
|---|---|
| Page | items وhasMore وnextCursor، من كل list مرقّم الصفحات. |
| PeoplePage | الشيء نفسه مع seen، من contacts().listPeople. |
| TempMessagesPage | الشيء نفسه مع expiresAt، من tempMail().listMessages. |
| AddressBookPage, AddressBook | unrestricted وaddresses وdomains، من addresses().list (مع hasMore وnextCursor) ومن addresses().listAll. |
| BatchResult | items وsent وfailed، من emails().sendBatch. |
| TemplateSends | items وtotal وpage وpageSize، من templates().listSends. |
| PagedIterable | مرور على كل الصفحات، من كل iterate: حلقة for أو stream() أو toList(). |
| Body, RequestOptions | ما يأخذه الاستدعاء: جسم طلب يحافظ على ترتيبه ويقبل القيم null، وخيارات استدعاء واحد. |
كل استثناء ترميه الحزمة هو OpenEmailException: ApiException وأصنافه الفرعية، وNetworkException وWebhookSignatureException. والخطأ في الاستدعاء نفسه يرمي IllegalArgumentException قبل إرسال أي شيء.
ما لا تفعله عن قصد
- لا يتحقق من أي متن طلب. فمخطط الخادم هو النسخة الوحيدة من القواعد، ونسخة ثانية هنا سترفض في النهاية عنوانًا يقبله خادم أحدث، في إصدار ثبّته أحدهم قبل عامين.
- تعيد تشكيل الاستجابة بطريقة واحدة فقط: قائمة
dataفي المجموعة تُخرَج من غلافها إلى أحد الأنواع أعلاه. وكل استجابة أخرى تعود كما أرسلتها الواجهة البرمجية، بمفاتيح الواجهة البرمجية بصيغة camelCase. - ليس فيها دوال غير متزامنة. يحجب الاستدعاء خيطه إلى أن يصل الجواب، وكلفة ذلك قليلة على خيط افتراضي.