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;

Casting getenv() to a string is deliberate. A variable that is not set becomes an empty key, which the client refuses with a message naming the variable it needs, where null would quietly fall back to 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,);

These throw OpenEmail\Exception\InvalidArgumentException from the line that had the wrong value in it, rather than surfacing as a confusing failure on your first send. The message says what was wrong and what to pass instead, and it never repeats a credential.

The class extends PHP’s own InvalidArgumentException, so code that already catches that keeps working, and it implements OpenEmail\Exception\OpenEmailException like every other exception the package throws. A value of the wrong type, such as a number where a string id goes, is a TypeError from PHP itself, because every method declares its types.

Build the client once and share it. A fresh client per request discards its open connection for nothing, and none of the state on it is per caller.

For the case that would otherwise force one client per key, such as a job sending on behalf of several workspaces, pass apiKey: on the call. It replaces the Authorization header for that request and leaves nothing behind on the 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);

Every method outside tempMail takes it as its last named argument, after the filters on a list, and the tempMail methods take inboxToken: instead. It is checked before the request is sent, by the same rule the client uses, so a typo throws an InvalidArgumentException about the apiKey passed to this call rather than a 401 about a credential you then have to go and find. A retried call keeps the key it was given.

$client->raw is the transport every method goes through. $client->raw->request() calls a path no method wraps yet, with the client’s credential, base URL, timeout and retry policy applied, and returns the decoded body the way a method does.

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

OpenEmail::createTempMail() builds a client for disposable inboxes that carries no API key and reads none from the environment. It creates inboxes anonymously, and each read sends the inbox token that create returned, or the newer one extend returned, either per call as inboxToken: or once as 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;

An app a person connected over OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as accessToken:, either the token itself or a callable that returns it, such as a closure or a first-class callable. The callable runs once for every call, and that call’s retries reuse what it returned, so renew the token inside it when it is close to expiring and the client never has to be rebuilt.

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

Before a sensitive change, such as deleting a domain or changing a webhook, the API asks an access token for the verification code the web app would ask the person for. The call throws a PermissionException, a 403 whose isStepUpRequired() is true, and nothing was changed. Ask for a code, verify the one the person gives you, then make the call again. An API key is never asked.

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

When a newer version of the package is on Packagist, the client says so once per process, on standard error, as a line such as ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1. followed by the package’s page. The check runs only on the command line, when standard output is a terminal, and never under a web server. It starts when the first client is built and runs beside your requests, and at the end of the script it waits for whatever is left of a two second budget. A failure to reach Packagist is ignored.

The default CurlHttpClient leaves proxies to cURL, which reads https_proxy or HTTPS_PROXY for the proxy and no_proxy or NO_PROXY for the hosts that go direct. Pass proxy: to name one in code instead. A user name and password in the proxy URL are sent to the 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],));