پرش به مستندات
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مبدأ API. به میزبان ساده‌ای مانند 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"]);

گزینه‌های یک فراخوانی

پارامترهای پرس‌وجو و تنظیم‌های فراخوانی آرگومان‌های نام‌دار با نام‌های API هستند، مانند 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 باشد.
  • نشانی پایه روی 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"]);