Configuration

use OpenEmail\OpenEmail; $client = new OpenEmail(); OpenEmail::init(timeout: 10);OpenEmail::getClient()->me->ping(); $billing = new OpenEmail(apiKey: (string) getenv('OPENEMAIL_BILLING_API_KEY')); echo $client->mode, ' ', $billing->mode, PHP_EOL;

Convertir getenv() en chaîne est voulu. Une variable non définie devient une clé vide, que le client refuse avec un message nommant la variable dont il a besoin, là où null se rabattrait silencieusement sur OPENEMAIL_API_KEY.

use OpenEmail\Http\CurlHttpClient;use OpenEmail\OpenEmail; $client = new OpenEmail(    apiKey: (string) getenv('OPENEMAIL_API_KEY'),    baseUrl: 'https://api.openemail.uk',    httpClient: new CurlHttpClient(),    maxRetries: 2,    timeout: 30,    userAgent: 'billing-service/1.4',    headers: ['X-Team' => 'billing'],    disableUpdateNotice: true,);

Ces cas lèvent OpenEmail\Exception\InvalidArgumentException 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.

La classe étend l'InvalidArgumentException propre à PHP : le code qui l'intercepte déjà continue donc de fonctionner, et elle implémente OpenEmail\Exception\OpenEmailException comme toute autre exception que lève le package. Une valeur du mauvais type, comme un nombre là où va un id sous forme de chaîne, est une TypeError de PHP lui-même, car chaque méthode déclare ses types.

Construisez le client une fois et partagez-le. Un nouveau client par requête jette sa connexion ouverte pour rien, et aucun de ses états n'est propre à un appelant.

Pour le cas qui imposerait sinon un client par clé, comme un job qui envoie pour le compte de plusieurs espaces de travail, passez apiKey: 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.',];$workspaceKey = (string) getenv('OPENEMAIL_API_KEY'); $client->emails->send($message); $client->emails->send($message, apiKey: $workspaceKey); $client->threads->list(folder: 'inbox', apiKey: $workspaceKey);$client->webhooks->list(apiKey: $workspaceKey);

Toute méthode hors de tempMail le prend comme dernier argument nommé, après les filtres d'une liste, et les méthodes de tempMail prennent inboxToken: à 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 InvalidArgumentException portant sur l'apiKey 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 décodé comme le fait une méthode.

$ping = $client->raw->request('/ping'); $label = $client->raw->request('/labels', method: 'POST', body: ['name' => 'Invoices']); var_dump($ping, $label);

OpenEmail::createTempMail() 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 inboxToken:, soit une fois via OpenEmail::createTempMail(inboxToken: ...).

use OpenEmail\OpenEmail; $tempMail = OpenEmail::createTempMail(); $inbox = $tempMail->create();$page = $tempMail->listMessages($inbox['id'], inboxToken: $inbox['token']); echo count($page->items), ' ', $page->expiresAt, PHP_EOL;

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 accessToken:, soit le jeton lui-même, soit un callable qui le renvoie, comme une closure ou un callable de première classe. Le callable s'exécute 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.

use OpenEmail\OpenEmail; $tokens = ['current' => 'token-from-your-oauth-flow']; $oauthClient = new OpenEmail(accessToken: fn(): string => $tokens['current']); $me = $oauthClient->me->get(); if ($me['object'] === 'oauth_token') {    echo $me['clientId'], ' ', $me['expiresAt'], PHP_EOL;}

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 PermissionException, un 403 dont isStepUpRequired() 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.

use OpenEmail\Exception\ApiException; $domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; try {    $client->domains->delete($domainId);} catch (ApiException $error) {    if (!$error->isStepUpRequired()) {        throw $error;    }     $challenge = $client->security->beginStepUp();     if ($challenge['method'] === 'email') {        echo 'Enter the code we emailed to ', $challenge['sentTo'], PHP_EOL;    } else {        echo 'Enter the code from your authenticator app, or a backup code', PHP_EOL;    }     $client->security->verifyStepUp(['code' => trim((string) fgets(STDIN))]);    $client->domains->delete($domainId);}

Quand une version plus récente du package est disponible sur Packagist, le client le signale une fois par processus, sur la sortie d'erreur standard, par une ligne comme ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1. suivie de la page du package. La vérification ne s'exécute qu'en ligne de commande, quand la sortie standard est un terminal, et jamais sous un serveur web. Elle démarre à la construction du premier client et s'exécute à côté de vos requêtes, et à la fin du script elle attend ce qui reste d'un budget de deux secondes. Un échec pour joindre Packagist est ignoré.

Le CurlHttpClient par défaut laisse les proxys à cURL, qui lit https_proxy ou HTTPS_PROXY pour le proxy et no_proxy ou NO_PROXY pour les hôtes joints directement. Passez proxy: pour en nommer un dans le code à la place. Un nom d'utilisateur et un mot de passe dans l'URL du proxy sont envoyés au proxy.

use OpenEmail\Http\CurlHttpClient;use OpenEmail\OpenEmail; $client = new OpenEmail(httpClient: new CurlHttpClient(    caBundle: '/etc/ssl/certs/corporate-ca.pem',    proxy: 'http://proxy.internal:3128',    curlOptions: [CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V4],));