Konfiguration

Jede Option des Clients, was er aus der Umgebung liest und was er ablehnt.

Optionen

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}");

Option	Was es tut
ApiKey	Der API-Schlüssel des Workspace, der mit `oe_live_` oder `oe_test_` beginnt.
AccessToken	Ein OAuth-Zugriffstoken für eine App, die eine Person verbunden hat. Übergeben Sie einen Schlüssel oder ein Token, nicht beides.
AccessTokenProvider	Eine Funktion, die das Zugriffstoken zurückgibt. Sie läuft vor jeder Anfrage und ist damit der Ort, ein Token zu erneuern.
BaseUrl	Der Ursprung der API. Ein bloßer Host wie `localhost:2222` bekommt sein Schema ergänzt.
HttpClient	Der `HttpClient`, den Ihre Anwendung schon hat, etwa einer aus `IHttpClientFactory` oder einer mit einem Test-Handler. Der Client gibt ihn nie frei.
Timeout	Wie lange ein Versuch dauern darf. Der Standard sind 30 Sekunden, `TimeSpan.Zero` schaltet es ab, und Uploads warten mindestens zehn Minuten.
MaxRetries	Wie oft eine fehlgeschlagene Anfrage erneut versucht wird. Der Standard ist 2, und 0 sendet einmal.
UserAgent	Ersetzt den Header `User-Agent`, der aus `openemail-dotnet/` und der Version besteht.
Headers	Header, die jeder Anfrage hinzugefügt werden.

Alles, was Sie weglassen, wird aus der Umgebung gelesen: OPENEMAIL_API_KEY, dann OPENEMAIL_ACCESS_TOKEN und OPENEMAIL_BASE_URL. client.Mode sagt, ob der Schlüssel ein live- oder ein test-Schlüssel ist.

Abbruch und Zeitlimits

Jede Methode nimmt zuletzt ein CancellationToken. Es abzubrechen beendet den Aufruf sofort, samt Wiederholungen, und löst OperationCanceledException aus, während Timeout jeden einzelnen Versuch begrenzt.

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"]);

Optionen bei einem Aufruf

Abfrageparameter und Aufrufeinstellungen sind benannte Argumente unter den Namen der API, etwa limit:, cursor: und idempotencyKey:. Jede Methode nimmt apiKey:, um nur für diesen Aufruf mit einem anderen Schlüssel zu handeln, sodass ein Prozess mit einem Client mehrere Workspaces bedienen kann.

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-Zugriffstoken

Eine App, die jemand über OAuth verbunden hat, hält ein Zugriffstoken statt eines API-Schlüssels. Übergeben Sie es als AccessToken, oder übergeben Sie AccessTokenProvider und erneuern Sie das Token dort, wenn es bald abläuft, sodass der Client nie neu gebaut werden muss.

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

Registrieren Sie einen Client für die gesamte Anwendung. Er hält keine eigene Verbindung, die freizugeben wäre, also ist ein Singleton die richtige Lebensdauer.

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();

Was der Client ablehnt

Einen Schlüssel, der nicht mit oe_live_ oder oe_test_ beginnt, und einen Schlüssel zusammen mit einem Zugriffstoken.
Das Senden von Zugangsdaten über einfaches http:, außer der Server läuft auf diesem Rechner unter localhost, einer 127.x.x.x-Adresse oder ::1.
Eine Basis-URL auf 0.0.0.0, einer Adresse, auf der ein Server lauscht. Verwenden Sie 127.0.0.1 mit demselben Port.
Eine leere ID oder eine, die nur aus Punkten besteht und die ein URL-Parser entfernen würde.
Einer Weiterleitung zu folgen. Der HTTP-Client, den das Paket baut, folgt nie einer, sodass Zugangsdaten nie zu einem anderen Host gelangen.

Die Ausgabe eines Clients oder einer Ausnahme zeigt nie Zugangsdaten. ToString() auf einem Client liefert seinen Modus und seine Basis-URL und sonst nichts.

Ein Endpunkt ohne Methode

client.Raw.RequestAsync() ruft jeden Pfad mit den Zugangsdaten, der Basis-URL, dem Zeitlimit und den Wiederholungsregeln des Clients auf. Der Pfad muss mit einem einzelnen / beginnen, und ein Pfad, der den Ursprung der Basis-URL verlässt, wird abgelehnt.

request.cs

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