Конфигурация

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;

Приведение getenv() к строке сделано намеренно. Незаданная переменная превращается в пустой ключ, который клиент отклоняет с сообщением, называющим нужную ему переменную, тогда как null молча откатился бы к 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,);

Эти случаи выбрасывают OpenEmail\Exception\InvalidArgumentException из той строки, где было неверное значение, а не всплывают непонятным сбоем при первой отправке. Сообщение говорит, что было не так и что передать вместо этого, и никогда не повторяет учётные данные.

Класс наследует собственный InvalidArgumentException из PHP, поэтому код, который уже его перехватывает, продолжает работать, и реализует OpenEmail\Exception\OpenEmailException, как и любое другое исключение, которое выбрасывает пакет. Значение неверного типа, например число там, где ожидается строковый id, приводит к TypeError от самого PHP, потому что каждый метод объявляет свои типы.

Соберите клиент один раз и разделяйте его. Новый клиент на каждый запрос впустую выбрасывает своё открытое соединение, а никакая часть его состояния не привязана к вызывающему.

Для случая, который иначе потребовал бы по клиенту на ключ, например задания, отправляющего от имени нескольких рабочих пространств, передайте apiKey: в вызов. Он заменяет заголовок Authorization для этого запроса и ничего не оставляет на клиенте.

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

Каждый метод вне tempMail принимает его последним именованным аргументом, после фильтров списка, а методы tempMail вместо него принимают inboxToken:. Он проверяется до отправки запроса по тому же правилу, что использует клиент, поэтому опечатка выбрасывает InvalidArgumentException про apiKey, переданный в этот вызов, а не 401 про учётные данные, которые потом ещё придётся искать. Повторный вызов сохраняет ключ, который ему дали.

$client->raw является транспортом, через который проходит каждый метод. $client->raw->request() вызывает путь, который пока не оборачивает ни один метод, применяя учётные данные клиента, базовый URL, таймаут и политику повторов, и возвращает декодированное тело так же, как это делает метод.

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

OpenEmail::createTempMail() собирает клиент для одноразовых ящиков, который не несёт API-ключа и не читает его из окружения. Он создаёт ящики анонимно, а каждое чтение отправляет токен ящика, который вернул create, или более новый, который вернул extend: либо в каждом вызове как inboxToken:, либо один раз как 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;

Приложение, которое человек подключил через OAuth, например инструмент командной строки или агент, держит токен доступа вместо API-ключа. Передайте его как accessToken:: либо сам токен, либо вызываемый объект, который его возвращает, например замыкание или first-class callable. Он выполняется один раз на каждый вызов, а повторы этого вызова переиспользуют то, что он вернул, поэтому обновляйте токен внутри него, когда срок действия подходит к концу, и клиент никогда не придётся пересобирать.

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

Перед чувствительным изменением, например удалением домена или изменением вебхука, API запрашивает у токена доступа код подтверждения, который веб-приложение запросило бы у человека. Вызов выбрасывает PermissionException, ошибку 403, у которой isStepUpRequired() равно true, и ничего не изменилось. Запросите код, проверьте тот, который даст вам человек, затем повторите вызов. У 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);}

Когда на Packagist есть более новая версия пакета, клиент сообщает об этом один раз за процесс в стандартный поток ошибок строкой вроде ℹ openemail/sdk 0.0.2 is available, you are on 0.0.1., за которой следует страница пакета. Проверка запускается только из командной строки, когда стандартный вывод является терминалом, и никогда под веб-сервером. Она начинается при сборке первого клиента и идёт параллельно с вашими запросами, а в конце скрипта ждёт столько, сколько осталось от бюджета в две секунды. Неудачная попытка связаться с Packagist игнорируется.

CurlHttpClient по умолчанию оставляет прокси на cURL, который читает https_proxy или HTTPS_PROXY для прокси и no_proxy или NO_PROXY для хостов, к которым подключение идёт напрямую. Чтобы задать прокси в коде, передайте proxy:. Имя пользователя и пароль из URL прокси отправляются самому прокси.

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