تخطَّ إلى المستندات
C#

الإعداد

كل خيار للعميل، وما يقرؤه من البيئة، وما يرفضه.

الخيارات

client.cs
using var http = new HttpClient(); var client = new OpenEmailClient(new OpenEmailOptions{    ApiKey = Environment.GetEnvironmentVariable("OPENEMAIL_API_KEY"),    BaseUrl = "https://api.openemail.uk",    Timeout = TimeSpan.FromSeconds(30),    MaxRetries = 2,    HttpClient = http,    Headers = { ["X-Team"] = "billing" },}); Console.WriteLine($"{client.Mode} {client.Raw.BaseUrl}");
الخيارما تفعله
ApiKeyمفتاح API لمساحة العمل، ويبدأ بـ oe_live_ أو oe_test_.
AccessTokenرمز وصول OAuth لتطبيق ربطه شخص ما. مرّر مفتاحًا أو رمزًا، لا كليهما.
AccessTokenProviderدالة تعيد رمز الوصول. تُنفَّذ قبل كل طلب، فهي المكان المناسب لتجديد الرمز.
BaseUrlأصل الواجهة البرمجية. المضيف المجرد مثل localhost:2222 يُضاف إليه المخطط.
HttpClientكائن HttpClient الموجود أصلًا في تطبيقك، مثل واحد من IHttpClientFactory أو واحد بمعالج اختبار. لا يتخلص العميل منه أبدًا.
Timeoutالمدة التي قد تستغرقها محاولة واحدة. القيمة الافتراضية 30 ثانية، وTimeSpan.Zero يعطّلها، وعمليات الرفع تنتظر عشر دقائق على الأقل.
MaxRetriesعدد مرات إعادة محاولة الطلب الفاشل. القيمة الافتراضية 2، و0 يرسل مرة واحدة.
UserAgentيستبدل الترويسة User-Agent، وهي openemail-dotnet/ متبوعة بالإصدار.
Headersترويسات تُضاف إلى كل طلب.

كل ما تتركه يُقرأ من البيئة: OPENEMAIL_API_KEY، ثم OPENEMAIL_ACCESS_TOKEN، وOPENEMAIL_BASE_URL. ويبيّن client.Mode هل المفتاح مفتاح live أم مفتاح test.

الإلغاء والمهلات

تأخذ كل دالة CancellationToken في الآخر. إلغاؤه يوقف الاستدعاء فورًا بما فيه إعادة المحاولات ويرمي OperationCanceledException، أما Timeout فيحد كل محاولة.

deadline.cs
using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(10)); var thread = await client.Threads.GetAsync("CAHk7pQ2x9LmZ4-mail.example.com", cancellationToken: deadline.Token); Console.WriteLine(thread["messageCount"]);

الخيارات في الاستدعاء

معاملات الاستعلام وإعدادات الاستدعاء وسائط مسمّاة بأسماء الواجهة البرمجية، مثل limit: وcursor: وidempotencyKey:. تأخذ كل دالة apiKey: لتعمل بمفتاح آخر لذلك الاستدعاء فقط، فيمكن لعملية واحدة أن تخدم عدة مساحات عمل بعميل واحد.

another-workspace.cs
var page = await client.Emails.ListAsync(    status: new[] { "failed", "bounced" },    limit: 50,    apiKey: Environment.GetEnvironmentVariable("OTHER_WORKSPACE_KEY")); Console.WriteLine($"{page.Count} {page.HasMore}");

رموز وصول OAuth

التطبيق الذي ربطه شخص عبر OAuth يحمل رمز وصول بدل مفتاح API. مرّره بصفته AccessToken، أو مرّر AccessTokenProvider وجدّد الرمز هناك حين يقترب انتهاء صلاحيته، فلا يحتاج العميل إلى إعادة بناء أبدًا.

access-token.cs
var current = "token-from-your-oauth-flow"; var client = new OpenEmailClient(new OpenEmailOptions{    AccessTokenProvider = _ => Task.FromResult(current),}); var me = await client.Me.GetAsync(); Console.WriteLine(me["workspaceId"]);

ASP.NET Core

سجّل عميلًا واحدًا للتطبيق كله. لا يحتفظ باتصال خاص به يجب التخلص منه، لذا فإن singleton هو العمر المناسب.

Program.cs
using OpenEmail; var builder = WebApplication.CreateBuilder(args); builder.Services.AddSingleton(new OpenEmailClient(new OpenEmailOptions{    ApiKey = builder.Configuration["OpenEmail:ApiKey"],})); var app = builder.Build(); app.MapPost("/invoices/{number}/send", async (string number, OpenEmailClient client, CancellationToken cancellationToken) =>{    var sent = await client.Emails.SendAsync(new Body    {        ["from"] = "[email protected]",        ["to"] = "[email protected]",        ["subject"] = $"Invoice {number}",        ["text"] = "The invoice is attached.",    }, idempotencyKey: $"invoice-{number}", cancellationToken: cancellationToken);     return Results.Ok(new { id = (string?)sent["id"] });}); app.Run();

ما يرفضه العميل

  • مفتاح لا يبدأ بـ oe_live_ أو oe_test_، ومفتاح مع رمز وصول معًا.
  • إرسال بيانات اعتماد عبر http: غير المشفر، إلا إذا كان الخادم على هذا الجهاز عند localhost أو عنوان 127.x.x.x أو ::1.
  • عنوان URL أساسي على 0.0.0.0، وهو عنوان يستمع عليه الخادم. استخدم 127.0.0.1 مع المنفذ نفسه.
  • معرّف فارغ، أو معرّف مكوّن من نقاط فقط، كان محلل عناوين URL سيحذفه.
  • اتباع إعادة التوجيه. عميل HTTP الذي تبنيه الحزمة لا يتبع أي إعادة توجيه، فلا تنتقل بيانات الاعتماد أبدًا إلى مضيف آخر.

طباعة عميل أو استثناء لا تُظهر أبدًا بيانات اعتماد. ToString() على العميل يعطي وضعه وعنوانه الأساسي ولا شيء غير ذلك.

نقطة نهاية بلا دالة

يستدعي client.Raw.RequestAsync() أي مسار ببيانات اعتماد العميل وعنوانه الأساسي ومهلته وسياسة إعادة المحاولة لديه. يجب أن يبدأ المسار بـ / واحدة، والمسار الذي يخرج عن أصل العنوان الأساسي يُرفض.

request.cs
var label = await client.Raw.RequestAsync("/labels", "POST", body: new Body { ["name"] = "Invoices" }); Console.WriteLine(label?["id"]);