Configuração

Cada opção do cliente, o que ele lê do ambiente e o que recusa.

Opções

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

Opção	O que faz
ApiKey	A chave de API do espaço de trabalho, que começa por `oe_live_` ou `oe_test_`.
AccessToken	Um token de acesso OAuth, para uma aplicação que uma pessoa ligou. Passe uma chave ou um token, não ambos.
AccessTokenProvider	Uma função que devolve o token de acesso. É executada antes de cada pedido, por isso é o sítio para renovar um token.
BaseUrl	A origem da API. A um host sem esquema, como `localhost:2222`, é acrescentado o esquema.
HttpClient	O `HttpClient` que a sua aplicação já tem, como um de `IHttpClientFactory` ou um com um handler de teste. O cliente nunca o liberta.
Timeout	Quanto tempo pode demorar uma tentativa. O valor predefinido é de 30 segundos, `TimeSpan.Zero` desativa-o, e os carregamentos esperam pelo menos dez minutos.
MaxRetries	Quantas vezes um pedido falhado é tentado de novo. O valor predefinido é 2, e 0 envia uma só vez.
UserAgent	Substitui o cabeçalho `User-Agent`, que é `openemail-dotnet/` seguido da versão.
Headers	Cabeçalhos acrescentados a todos os pedidos.

Tudo o que omitir é lido do ambiente: OPENEMAIL_API_KEY, depois OPENEMAIL_ACCESS_TOKEN, e OPENEMAIL_BASE_URL. client.Mode indica se a chave é uma chave live ou test.

Cancelamento e tempos limite

Cada método recebe um CancellationToken em último lugar. Cancelá-lo interrompe a chamada de imediato, novas tentativas incluídas, e lança OperationCanceledException, enquanto Timeout limita cada tentativa.

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

Opções de uma chamada

Os parâmetros de consulta e as definições da chamada são argumentos nomeados com os nomes da API, como limit:, cursor: e idempotencyKey:. Cada método aceita apiKey: para agir com outra chave apenas nessa chamada, por isso um processo pode servir vários espaços de trabalho com um só cliente.

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

Tokens de acesso OAuth

Uma aplicação que uma pessoa ligou com OAuth tem um token de acesso em vez de uma chave de API. Passe-o como AccessToken, ou passe AccessTokenProvider e renove aí o token quando estiver prestes a expirar, para que o cliente nunca tenha de ser recriado.

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

Registe um só cliente para toda a aplicação. Não mantém nenhuma ligação própria para libertar, por isso um singleton é o tempo de vida certo.

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

O que o cliente recusa

Uma chave que não começa por oe_live_ ou oe_test_, e uma chave juntamente com um token de acesso.
Enviar uma credencial por http: simples, a menos que o servidor esteja nesta máquina, em localhost, num endereço 127.x.x.x ou em ::1.
Um URL base em 0.0.0.0, que é um endereço em que um servidor escuta. Use 127.0.0.1 com a mesma porta.
Um id vazio, ou feito apenas de pontos, que um analisador de URL removeria.
Seguir um redirecionamento. O cliente HTTP que o pacote cria nunca segue nenhum, por isso uma credencial nunca viaja para outro host.

Imprimir um cliente ou uma exceção nunca mostra uma credencial. ToString() num cliente dá o seu modo e o seu URL base, e mais nada.

Um endpoint sem método

client.Raw.RequestAsync() chama qualquer caminho com a credencial, o URL base, o tempo limite e a política de novas tentativas do cliente. O caminho tem de começar por uma única /, e um caminho que sai da origem do URL base é recusado.

request.cs

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