구성
클라이언트의 모든 옵션, 환경에서 읽는 것, 거부하는 것.
옵션
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는 제한을 끄며, 업로드는 최소 10분을 기다립니다. |
| 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은 각 시도를 제한합니다.
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:를 받아 해당 호출에서만 다른 키로 동작하므로, 하나의 프로세스가 하나의 클라이언트로 여러 워크스페이스를 처리할 수 있습니다.
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를 전달하고 만료가 가까워지면 그곳에서 토큰을 갱신하세요. 그러면 클라이언트를 다시 만들 필요가 없습니다.
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
애플리케이션 전체에 클라이언트 하나를 등록하세요. 해제해야 할 자체 연결이 없으므로 싱글턴이 알맞은 수명입니다.
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의 기본 URL. 이는 서버가 수신 대기하는 주소입니다. 같은 포트로127.0.0.1을 사용하세요.- 빈 id 또는 점으로만 이루어진 id. URL 파서가 제거해 버립니다.
- 리디렉션을 따라가는 것. 패키지가 만드는 HTTP 클라이언트는 리디렉션을 절대 따라가지 않으므로 자격 증명이 다른 호스트로 넘어가지 않습니다.
클라이언트나 예외를 출력해도 자격 증명은 절대 표시되지 않습니다. 클라이언트의 ToString()은 모드와 기본 URL만 반환합니다.
메서드가 없는 엔드포인트
client.Raw.RequestAsync()는 클라이언트의 자격 증명, 기본 URL, 타임아웃, 재시도 정책으로 어떤 경로든 호출합니다. 경로는 하나의 /로 시작해야 하며, 기본 URL의 오리진을 벗어나는 경로는 거부됩니다.
var label = await client.Raw.RequestAsync("/labels", "POST", body: new Body { ["name"] = "Invoices" }); Console.WriteLine(label?["id"]);