Configuration

Chaque option du client, ce qu'il lit dans l'environnement et ce qu'il refuse.

Options

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	Ce qu'il fait
ApiKey	La clé d'API de l'espace de travail, qui commence par `oe_live_` ou `oe_test_`.
AccessToken	Un jeton d'accès OAuth, pour une application qu'une personne a connectée. Passez une clé ou un jeton, pas les deux.
AccessTokenProvider	Une fonction qui renvoie le jeton d'accès. Elle s'exécute avant chaque requête : c'est donc l'endroit où renouveler un jeton.
BaseUrl	L'origine de l'API. Un hôte nu comme `localhost:2222` reçoit son schéma.
HttpClient	Le `HttpClient` que votre application possède déjà, par exemple celui d'une `IHttpClientFactory` ou un client doté d'un gestionnaire de test. Le client ne le libère jamais.
Timeout	Le temps que peut prendre une tentative. La valeur par défaut est de 30 secondes, `TimeSpan.Zero` le désactive, et les téléversements attendent au moins dix minutes.
MaxRetries	Le nombre de fois où une requête en échec est retentée. La valeur par défaut est 2, et 0 n'envoie qu'une fois.
UserAgent	Remplace l'en-tête `User-Agent`, qui vaut `openemail-dotnet/` suivi de la version.
Headers	Des en-têtes ajoutés à chaque requête.

Tout ce que vous omettez est lu dans l'environnement : OPENEMAIL_API_KEY, puis OPENEMAIL_ACCESS_TOKEN, et OPENEMAIL_BASE_URL. client.Mode indique si la clé est une clé live ou une clé test.

Annulation et délais

Chaque méthode prend un CancellationToken en dernier. L'annuler arrête l'appel aussitôt, nouvelles tentatives comprises, et lève OperationCanceledException, tandis que Timeout borne chaque tentative.

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

Options d'un appel

Les paramètres de requête et les réglages d'appel sont des arguments nommés qui portent les noms de l'API, comme limit:, cursor: et idempotencyKey:. Chaque méthode prend apiKey: pour agir avec une autre clé pour cet appel seulement : un seul processus peut donc servir plusieurs espaces de travail avec un seul client.

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

Jetons d'accès OAuth

Une application qu'une personne a connectée avec OAuth détient un jeton d'accès plutôt qu'une clé API. Passez-le comme AccessToken, ou passez AccessTokenProvider et renouvelez-y le jeton quand il approche de son expiration : le client n'a ainsi jamais à être reconstruit.

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

Enregistrez un seul client pour toute l'application. Il ne détient aucune connexion à libérer : un singleton est donc la bonne durée de vie.

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

Ce que le client refuse

Une clé qui ne commence pas par oe_live_ ou oe_test_, et une clé accompagnée d'un jeton d'accès.
L'envoi d'un identifiant en http: simple, sauf si le serveur est sur cette machine, à localhost, à une adresse 127.x.x.x ou à ::1.
Une URL de base sur 0.0.0.0, qui est une adresse sur laquelle un serveur écoute. Utilisez 127.0.0.1 avec le même port.
Un identifiant vide, ou fait uniquement de points, qu'un analyseur d'URL supprimerait.
Suivre une redirection. Le client HTTP que le package construit n'en suit jamais : un identifiant ne part donc jamais vers un autre hôte.

Afficher un client ou une exception ne montre jamais un identifiant. ToString() sur un client donne son mode et son URL de base, et rien d'autre.

Un point de terminaison sans méthode

client.Raw.RequestAsync() appelle n'importe quel chemin avec l'identifiant, l'URL de base, le délai et la politique de nouvelles tentatives du client. Le chemin doit commencer par un seul /, et un chemin qui quitte l'origine de l'URL de base est refusé.

request.cs

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