구성

이들은 첫 발송에서 알기 어려운 실패로 나타나는 대신, 잘못된 값이 들어간 바로 그 줄에서 ArgumentError를 발생시킵니다. 메시지는 무엇이 잘못되었고 대신 무엇을 전달해야 하는지 알려 주며, 자격 증명을 되풀이해 보여 주지 않습니다.

클라이언트는 한 번 만들어 공유하세요. 요청마다 새 클라이언트를 만들면 열린 연결을 헛되이 버리는 셈이고, 클라이언트에 담긴 상태 중 호출자별로 달라지는 것은 없습니다. 클라이언트는 만들어진 뒤 동결되며 여러 스레드에서 동시에 사용해도 안전하므로, Puma나 Sidekiq 프로세스에는 하나만 있으면 되고, fork한 뒤에는 자식 프로세스가 자신의 연결을 엽니다.

여러 워크스페이스를 대신해 발송하는 작업처럼 키마다 클라이언트를 만들어야 할 상황에서는 호출에 api_key:를 전달하세요. 그 요청에 한해 Authorization 헤더를 대체하며 클라이언트에는 아무것도 남기지 않습니다.

message = {from: "[email protected]", to: "[email protected]", subject: "Your invoice", text: "Attached."}workspace_key = ENV.fetch("OPENEMAIL_API_KEY") client.emails.send(message) client.emails.send(message, api_key: workspace_key) client.threads.list(folder: "inbox", api_key: workspace_key)client.webhooks.list(api_key: workspace_key)

temp_mail 밖의 모든 메서드가 목록의 필터와 나란히 이 값을 키워드 인자로 받으며, temp_mail의 메서드는 대신 inbox_token:을 받습니다. 이 값은 클라이언트와 같은 규칙으로 요청 전에 검사되므로, 오타가 나면 나중에 찾아 헤매야 할 자격 증명에 대한 401이 아니라 이 호출에 전달한 api_key에 관한 ArgumentError가 발생합니다. 재시도된 호출은 받은 키를 그대로 유지합니다.

client.raw는 모든 메서드가 거치는 전송 계층입니다. client.raw.request는 아직 어떤 메서드도 감싸지 않는 경로를, 클라이언트의 자격 증명, 기본 URL, 타임아웃, 재시도 정책을 적용해 호출하고, 메서드와 마찬가지로 파싱된 본문을 반환합니다.

ping = client.raw.request("/ping") label = client.raw.request("/labels", method: :post, body: {name: "Invoices"}) p ping[:ok], label[:id]

OpenEmail.create_temp_mail은 API 키를 담지 않고 환경 변수에서도 읽지 않는 일회용 받은편지함용 클라이언트를 만듭니다. 익명으로 받은편지함을 만들고, 읽을 때마다 create가 반환한 받은편지함 토큰이나 extend가 반환한 더 새로운 토큰을 호출별 inbox_token:으로 보내거나 OpenEmail.create_temp_mail(inbox_token:)으로 한 번에 지정합니다.

temp_mail = OpenEmail.create_temp_mail inbox = temp_mail.createpage = temp_mail.list_messages(inbox[:id], inbox_token: inbox[:token]) p page.items.size, page.expires_at

명령줄 도구나 에이전트처럼 사용자가 OAuth로 연결한 앱은 API 키 대신 액세스 토큰을 가집니다. 이를 access_token:으로 전달하세요. 토큰 자체이거나, lambda나 Method처럼 call에 응답해 토큰을 반환하는 객체입니다. 이 객체는 호출마다 한 번 불리고, 그 호출의 재시도는 반환된 값을 다시 씁니다. 그러니 만료가 가까워지면 그 안에서 토큰을 갱신하세요. 클라이언트를 다시 만들 필요가 없습니다.

tokens = {current: "token-from-your-oauth-flow"} oauth_client = OpenEmail::Client.new(access_token: -> { tokens.fetch(:current) }) me = oauth_client.me.get puts me[:clientId], me[:expiresAt] if me[:object] == "oauth_token"

도메인 삭제나 웹훅 변경 같은 민감한 변경 전에 API는 액세스 토큰에게, 웹 앱이 사용자에게 요구할 인증 코드를 요구합니다. 호출은 step_up_required?가 true인 403, 즉 OpenEmail::PermissionError를 발생시키며, 아무것도 바뀌지 않았습니다. 코드를 요청하고 사용자가 준 코드를 인증한 뒤 다시 호출하세요. API 키는 요구받지 않습니다.

domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" begin  client.domains.delete(domain_id)rescue OpenEmail::ApiError => error  raise unless error.step_up_required?   challenge = client.security.begin_step_up   if challenge[:method] == "email"    puts "Enter the code we emailed to #{challenge[:sentTo]}"  else    puts "Enter the code from your authenticator app, or a backup code"  end   client.security.verify_step_up(code: $stdin.gets.to_s.strip)  client.domains.delete(domain_id)end

RubyGems에 gem의 새 버전이 있으면 클라이언트는 프로세스당 한 번, 표준 오류에 ℹ openemail 0.0.2 is available, you are on 0.0.1. 같은 줄과 gem의 페이지를 출력해 알려 줍니다. 이 확인은 첫 클라이언트를 만들 때 2초 타임아웃이 걸린 백그라운드 스레드에서, 표준 출력이 터미널일 때만 실행되며, RubyGems에 연결하지 못해도 무시됩니다.

기본 어댑터는 Ruby 자체의 URI#find_proxy로 프록시를 찾으므로, 표준 라이브러리의 나머지 부분과 같은 규칙을 따릅니다: https_proxy 또는 HTTPS_PROXY가 프록시를 지정하고, no_proxy 또는 NO_PROXY가 직접 연결할 호스트를 나열합니다. 프록시 URL에 들어 있는 사용자 이름과 비밀번호는 프록시로 전송되며, 이 컴퓨터의 서버에는 프록시를 거쳐 연결하지 않습니다.

adapter:는 HTTP 계층을 대체합니다. lambda를 포함해 call(request)에 응답하는 것이면 무엇이든 되며, status, headers, body를 가진 OpenEmail::HttpResponse를 반환합니다. 요청은 method, url, headers, body, timeout을 가진 OpenEmail::HttpRequest이므로, 테스트는 실제로 나갔을 내용을 정확히 확인할 수 있습니다.

requests = [] adapter = lambda do |request|  requests << request  OpenEmail::HttpResponse.new(    status: 200,    headers: {"content-type" => "application/json"},    body: JSON.generate({id: "msg_test", status: "sent", replayed: false})  )end test_client = OpenEmail::Client.new(api_key: "oe_test_fake", adapter:, max_retries: 0, disable_update_notice: true) sent = test_client.emails.send(from: "[email protected]", to: "[email protected]", subject: "Hi", text: "Hello") p sent[:status], requests.first.method, requests.first.url, requests.first.headers["Idempotency-Key"]p requests.first

요청을 출력하면 Authorization 헤더가 [redacted]로 표시되므로, 테스트 로그에 키가 남지 않습니다.

• —{"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}처럼 API의 오류 봉투를 본문으로 하여 2xx 이외의 상태를 반환하면, 그에 맞는 OpenEmail::ApiError 하위 클래스를 얻습니다.
• —call에서 Timeout::Error 또는 그 일종인 Net::ReadTimeout을 발생시키면 timeout?이 true인 OpenEmail::NetworkError를 얻습니다. Errno::ECONNREFUSED 같은 그 밖의 StandardError는 timeout?이 false인 NetworkError가 됩니다.
• —어댑터 안에서 발생한 NameError, TypeError, ArgumentError는 어댑터의 버그로 간주됩니다. 그대로 발생하며 재시도되지 않습니다.