Konfiguration

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;

Dass getenv() in einen String umgewandelt wird, ist Absicht. Eine nicht gesetzte Variable wird zu einem leeren Schlüssel, den der Client mit einer Meldung ablehnt, die die benötigte Variable nennt, während null stillschweigend auf OPENEMAIL_API_KEY zurückfallen würde.

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,);

Diese Fälle werfen eine OpenEmail\Exception\InvalidArgumentException in der Zeile, die den falschen Wert enthielt, statt erst als verwirrender Fehlschlag bei Ihrem ersten Versand aufzutauchen. Die Meldung sagt, was falsch war und was Sie stattdessen übergeben sollten, und gibt nie Zugangsdaten wieder.

Die Klasse erweitert PHPs eigene InvalidArgumentException, Code, der diese bereits abfängt, funktioniert also weiter, und sie implementiert OpenEmail\Exception\OpenEmailException wie jede andere Exception, die das Paket wirft. Ein Wert vom falschen Typ, etwa eine Zahl, wo eine String-id hingehört, ist ein TypeError von PHP selbst, weil jede Methode ihre Typen deklariert.

Erzeugen Sie den Client einmal und teilen Sie ihn. Ein neuer Client pro Anfrage verwirft seine offene Verbindung ohne Nutzen, und nichts von seinem Zustand gehört zu einem bestimmten Aufrufer.

Für den Fall, der sonst einen Client pro Schlüssel erzwingen würde, etwa einen Job, der im Namen mehrerer Workspaces sendet, übergeben Sie apiKey: beim Aufruf. Er ersetzt den Authorization-Header für diese Anfrage und hinterlässt nichts am 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);

Jede Methode außerhalb von tempMail nimmt ihn als letztes benanntes Argument entgegen, nach den Filtern einer Liste, und die tempMail-Methoden nehmen stattdessen inboxToken:. Er wird vor dem Senden der Anfrage nach derselben Regel geprüft, die der Client verwendet. Ein Tippfehler wirft daher eine InvalidArgumentException zum apiKey dieses Aufrufs statt eines 401 zu Zugangsdaten, die Sie dann erst suchen müssen. Ein wiederholter Aufruf behält den Schlüssel, den er erhalten hat.

$client->raw ist der Transport, über den jede Methode läuft. $client->raw->request() ruft einen Pfad auf, den noch keine Methode kapselt, mit den Zugangsdaten, der Basis-URL, dem Timeout und den Wiederholungsregeln des Clients, und gibt den dekodierten Body so zurück, wie es eine Methode tut.

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

OpenEmail::createTempMail() erzeugt einen Client für Wegwerf-Posteingänge, der keinen API-Schlüssel trägt und keinen aus der Umgebung liest. Er legt Posteingänge anonym an, und jeder Lesezugriff sendet das Posteingangs-Token, das create zurückgegeben hat, oder das neuere, das extend zurückgegeben hat, entweder pro Aufruf als inboxToken: oder einmalig als 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;

Eine App, die jemand über OAuth verbunden hat, etwa ein Kommandozeilenwerkzeug oder ein Agent, hält ein Zugriffstoken statt eines API-Schlüssels. Übergeben Sie es als accessToken:, entweder das Token selbst oder ein Callable, das es zurückgibt, etwa eine Closure oder ein First-Class-Callable. Das Callable läuft einmal pro Aufruf, und die Wiederholungen dieses Aufrufs verwenden, was es zurückgab. Erneuern Sie das Token also darin, wenn es bald abläuft, dann muss der Client nie neu erzeugt werden.

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;}

Vor einer heiklen Änderung, etwa dem Löschen einer Domain oder dem Ändern eines Webhooks, verlangt die API von einem Zugriffstoken den Bestätigungscode, den die Web-App von der Person verlangen würde. Der Aufruf wirft eine PermissionException, einen 403, dessen isStepUpRequired() true ist, und es wurde nichts geändert. Fordern Sie einen Code an, bestätigen Sie den, den die Person Ihnen gibt, und rufen Sie dann erneut auf. Ein API-Schlüssel wird nie gefragt.

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);}

Wenn bei Packagist eine neuere Version des Pakets vorliegt, meldet der Client das einmal pro Prozess auf der Standardfehlerausgabe, als Zeile wie ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1., gefolgt von der Seite des Pakets. Die Prüfung läuft nur auf der Kommandozeile, wenn die Standardausgabe ein Terminal ist, und nie unter einem Webserver. Sie startet, wenn der erste Client erzeugt wird, und läuft neben Ihren Anfragen, und am Ende des Skripts wartet sie auf den Rest eines Budgets von zwei Sekunden. Ist Packagist nicht erreichbar, wird das ignoriert.

Der Standard-CurlHttpClient überlässt Proxys cURL, das https_proxy oder HTTPS_PROXY für den Proxy und no_proxy oder NO_PROXY für die Hosts liest, die direkt erreicht werden. Übergeben Sie stattdessen proxy:, um einen im Code zu nennen. Benutzername und Passwort in der Proxy-URL werden an den Proxy gesendet.

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],));