設定

これらは、最初の送信で分かりにくい失敗として表面化するのではなく、誤った値を含む行から ArgumentError を送出します。メッセージには何が誤っていて代わりに何を渡すべきかが書かれ、資格情報がそのまま繰り返されることはありません。

クライアントは一度作って共有してください。リクエストごとに新しいクライアントを作ると、開いている接続を無駄に捨てることになり、しかもその状態に呼び出し元ごとのものは何もありません。クライアントは作成されると凍結され、多数のスレッドから同時に使っても安全なので、Puma や Sidekiq のプロセスには 1 つあれば足ります。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 に応答してトークンを返すものを渡せます。これは呼び出しごとに 1 回呼ばれ、その呼び出しのリトライは返された値を再利用するため、期限切れが近づいたらその中でトークンを更新すれば、クライアントを作り直す必要はありません。

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"

ドメインの削除や Webhook の変更などの重要な変更の前に、API はアクセストークンに対し、Web アプリが本人に求めるのと同じ確認コードを求めます。呼び出しは OpenEmail::PermissionError を送出します。これは step_up_required? が true の 403 で、何も変更されていません。コードを求め、本人から受け取ったコードを確認してから、もう一度呼び出してください。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 の新しいバージョンがあると、クライアントはプロセスごとに 1 回、標準エラーに ℹ 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 層を置き換えます。call(request) に応答するものなら lambda を含め何でもよく、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] と表示されるため、テストのログにキーが残ることはありません。

• —対応する OpenEmail::ApiError のサブクラスを得るには、{"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}} のように、API のエラーエンベロープをボディにした 2xx 以外のステータスを返します。
• —timeout? が true の OpenEmail::NetworkError を得るには、call から Timeout::Error、またはその一種である Net::ReadTimeout を送出します。Errno::ECONNREFUSED など、それ以外の StandardError は timeout? が false の NetworkError になります。
• —アダプター内で送出された NameError、TypeError、ArgumentError は、アダプター自体のバグとして扱われます。そのまま送出され、リトライされることはありません。