Configuration

Ces cas lèvent ArgumentError depuis la ligne qui contenait la mauvaise valeur, au lieu d'apparaître comme un échec déroutant lors de votre premier envoi. Le message indique ce qui n'allait pas et ce qu'il faut passer à la place, et il ne répète jamais un identifiant.

Construisez le client une fois et partagez-le. Un nouveau client par requête jette ses connexions ouvertes pour rien, et aucun de ses états n'est propre à un appelant. Un client est gelé une fois construit et peut être utilisé sans risque depuis de nombreux threads à la fois : un processus Puma ou Sidekiq n'en a donc besoin que d'un, et après un fork, le processus enfant ouvre ses propres connexions.

Pour le cas qui imposerait sinon un client par clé, comme un job qui envoie pour le compte de plusieurs espaces de travail, passez api_key: sur l'appel. Il remplace l'en-tête Authorization pour cette requête et ne laisse rien derrière lui sur le client.

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)

Toute méthode hors de temp_mail le prend comme argument nommé, à côté des filtres d'une liste, et les méthodes de temp_mail prennent inbox_token: à la place. Il est vérifié avant l'envoi de la requête, selon la même règle que celle du client : une faute de frappe lève donc une ArgumentError portant sur l'api_key passée à cet appel, plutôt qu'un 401 sur un identifiant qu'il vous faudrait ensuite retrouver. Un appel réessayé garde la clé qui lui a été donnée.

client.raw est le transport par lequel passe chaque méthode. client.raw.request appelle un chemin qu'aucune méthode n'encapsule encore, en appliquant l'identifiant, l'URL de base, le délai et la politique de réessai du client, et renvoie le corps analysé comme le fait une méthode.

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

OpenEmail.create_temp_mail construit un client pour boîtes jetables qui ne porte aucune clé API et n'en lit aucune dans l'environnement. Il crée des boîtes anonymement, et chaque lecture envoie le jeton de boîte renvoyé par create, ou le plus récent renvoyé par extend, soit par appel via inbox_token:, soit une fois via 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

Une application qu'une personne a connectée en OAuth, comme un outil en ligne de commande ou un agent, détient un jeton d'accès plutôt qu'une clé API. Passez-le comme access_token:, soit le jeton lui-même, soit tout objet qui répond à call et le renvoie, comme une lambda ou une Method. Cet objet est appelé une fois par appel, et les réessais de cet appel réutilisent ce qu'il a renvoyé : renouvelez donc le jeton à l'intérieur quand il approche de son expiration, et le client n'aura jamais à être reconstruit.

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"

Avant un changement sensible, comme supprimer un domaine ou modifier un webhook, l'API demande à un jeton d'accès le code de vérification que l'application web demanderait à la personne. L'appel lève une OpenEmail::PermissionError, un 403 dont step_up_required? vaut true, et rien n'a été modifié. Demandez un code, vérifiez celui que la personne vous donne, puis refaites l'appel. On ne le demande jamais à une clé 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

Quand une version plus récente de la gem est disponible sur RubyGems, le client le signale une fois par processus, sur la sortie d'erreur standard, par une ligne comme ℹ openemail 0.0.2 is available, you are on 0.0.1. suivie de la page de la gem. La vérification s'exécute à la construction du premier client, dans un thread d'arrière-plan avec un délai de deux secondes, seulement quand la sortie standard est un terminal, et un échec pour joindre RubyGems est ignoré.

L'adaptateur par défaut trouve son proxy avec URI#find_proxy, propre à Ruby : il suit donc les mêmes règles que le reste de la bibliothèque standard. https_proxy ou HTTPS_PROXY nomme le proxy, et no_proxy ou NO_PROXY liste les hôtes joints directement. Un nom d'utilisateur et un mot de passe dans l'URL du proxy sont envoyés au proxy, et un serveur sur cette machine n'est jamais joint par un proxy.

adapter: remplace la couche HTTP. C'est tout objet qui répond à call(request), lambda comprise, et renvoie une OpenEmail::HttpResponse avec status, headers et body. La requête est une OpenEmail::HttpRequest avec method, url, headers, body et timeout : un test peut donc vérifier exactement ce qui serait parti.

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

L'affichage d'une requête montre son en-tête Authorization sous la forme [redacted] : un journal de test ne contient donc jamais la clé.

• —Renvoyez un statut hors de 2xx avec l'enveloppe d'erreur de l'API comme corps, par exemple {"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}, pour obtenir la sous-classe d'OpenEmail::ApiError correspondante.
• —Levez Timeout::Error depuis call, ou Net::ReadTimeout, qui en est une, pour obtenir une OpenEmail::NetworkError dont timeout? vaut true. Toute autre StandardError, comme Errno::ECONNREFUSED, devient une NetworkError dont timeout? vaut false.
• —NameError, TypeError et ArgumentError levées dans l'adaptateur comptent comme des bugs de celui-ci. Elles sont relevées telles quelles et jamais réessayées.