Configuración

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 una cadena es deliberado. Una variable sin definir se convierte en una clave vacía, que el cliente rechaza con un mensaje que nombra la variable que necesita, mientras que null recurriría en silencio a 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,);

Estos casos lanzan OpenEmail\Exception\InvalidArgumentException desde la línea que contenía el valor incorrecto, en lugar de aparecer como un fallo confuso en tu primer envío. El mensaje indica qué estaba mal y qué pasar en su lugar, y nunca repite una credencial.

La clase extiende la InvalidArgumentException propia de PHP, así que el código que ya la captura sigue funcionando, e implementa OpenEmail\Exception\OpenEmailException como cualquier otra excepción que lanza el paquete. Un valor del tipo incorrecto, como un número donde va un id de tipo cadena, es un TypeError del propio PHP, porque cada método declara sus tipos.

Construye el cliente una vez y compártelo. Un cliente nuevo por solicitud desecha su conexión abierta sin ganar nada, y ninguno de sus estados es propio de cada llamante.

Para el caso que de otro modo obligaría a un cliente por clave, como un trabajo que envía en nombre de varios espacios de trabajo, pasa apiKey: en la llamada. Sustituye la cabecera Authorization de esa solicitud y no deja nada en el cliente.

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

Todos los métodos fuera de tempMail la aceptan como su último argumento nombrado, después de los filtros en una lista, y los métodos de tempMail aceptan inboxToken: en su lugar. Se comprueba antes de enviar la solicitud, con la misma regla que usa el cliente, así que una errata lanza una InvalidArgumentException sobre la apiKey pasada a esta llamada en lugar de un 401 sobre una credencial que luego tienes que ir a buscar. Una llamada reintentada conserva la clave que recibió.

$client->raw es el transporte por el que pasa cada método. $client->raw->request() llama a una ruta que ningún método envuelve todavía, aplicando la credencial, la URL base, el tiempo de espera y la política de reintentos del cliente, y devuelve el cuerpo decodificado igual que un método.

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

OpenEmail::createTempMail() construye un cliente para buzones desechables que no lleva ninguna clave de API ni lee ninguna del entorno. Crea buzones de forma anónima, y cada lectura envía el token de buzón que devolvió create, o el más reciente que devolvió extend, bien por llamada como inboxToken:, bien una sola vez como 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;

Una app que una persona conectó por OAuth, como una herramienta de línea de comandos o un agente, tiene un token de acceso en lugar de una clave de API. Pásalo como accessToken:, ya sea el propio token o un callable que lo devuelva, como un closure o un callable de primera clase. El callable se ejecuta una vez por cada llamada, y los reintentos de esa llamada reutilizan lo que devolvió, así que renueva el token dentro de él cuando esté a punto de caducar y nunca tendrás que reconstruir el cliente.

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

Antes de un cambio delicado, como eliminar un dominio o cambiar un webhook, la API pide a un token de acceso el código de verificación que la app web le pediría a la persona. La llamada lanza una PermissionException, un 403 cuyo isStepUpRequired() es true, y no se cambió nada. Pide un código, verifica el que te dé la persona y vuelve a hacer la llamada. A una clave de API nunca se le pide.

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

Cuando hay una versión más reciente del paquete en Packagist, el cliente lo dice una vez por proceso, en la salida de error estándar, con una línea como ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1. seguida de la página del paquete. La comprobación solo se ejecuta en la línea de comandos, cuando la salida estándar es una terminal, y nunca bajo un servidor web. Empieza al construir el primer cliente y corre junto a tus solicitudes, y al final del script espera lo que quede de un margen de dos segundos. Si no se puede llegar a Packagist, se ignora.

El CurlHttpClient por defecto deja los proxies a cURL, que lee https_proxy o HTTPS_PROXY para el proxy y no_proxy o NO_PROXY para los hosts a los que se va directamente. Pasa proxy: para indicar uno en el código. Un nombre de usuario y una contraseña en la URL del proxy se envían al 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],));