Черновики
`drafts->list`, `listAll`, `iterate`, `get`, `create`, `update` и `delete`.
Все методы
$page = $client->drafts->list(query: 'invoice', limit: 25);$draft = $client->drafts->get('draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8');echo count($page), ' ', $draft['subject'], PHP_EOL; $created = $client->drafts->create([ 'to' => ['[email protected]'], 'cc' => [], 'bcc' => [], 'subject' => 'Your September invoice', 'html' => '<p>Draft body.</p>', 'from' => '[email protected]', 'threadId' => 'CAHk7pQ2x9LmZ4-mail.example.com',]); $updated = $client->drafts->update($created['id'], ['subject' => 'Revised']);$client->drafts->delete($updated['id']);update сохраняет идентификатор черновика, поэтому в ответе всегда тот идентификатор, который вы передали. Неизвестный идентификатор даёт 404, выбрасываемый как NotFoundException, а не новый черновик.
Поля черновика являются ключами одного массива с именами из API, поэтому цепочка, на которую отвечает черновик, задаётся как threadId. Черновик возвращается как массив с ключами в camelCase, поэтому $draft['subject'] читает тему. Каждая запись отвечает только object и id, поэтому весь черновик читайте через get.
list листает так же, как threads->list. pageToken из API возвращается как nextCursor и передаётся как cursor:, а listAll и iterate следуют за ним за вас. iterate возвращает Generator, который выдаёт по одному черновику за раз. Страница содержит 25 черновиков, если limit: не запросит до 100. query: принимает синтаксис поиска threads->list, и поиск никогда не выходит за пределы черновиков. Строка содержит только object и id, поэтому за получателями, темой и телом вызывайте get.
Список черновиков не сообщает hasMore, поэтому hasMore истинно всякий раз, когда вернулся курсор. Сервер предлагает курсор всякий раз, когда страница заполнена, поэтому за последней страницей, которая оказалась заполненной, следует одна пустая.
Черновик хранится как цепочка с ярлыком DRAFT, поэтому $client->threads->list(folder: 'draft') выводит те же черновики. get, update и delete отвечают на идентификатор обычной цепочки ошибкой 404, хотя threads->get его открывает. delete удаляет черновик навсегда. Он не попадает в корзину, и отменить это нельзя.
Чтобы отправить черновик, передайте его идентификатор в emails->send как draftId. Черновик даёт содержимое, а отправка даёт конверт. Черновик нельзя сочетать с template или translate.
$client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'draftId' => 'draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8',]);Параметры: drafts->create и drafts->update
toarray- Адреса получателей в виде списка строк, а не в формах массива, которые принимает `emails->send`, потому что этот эндпоинт склеивает список в строку через запятую, которая нужна драйверу. Строка может содержать отображаемое имя, как в `Ada Lovelace <[email protected]>`, но имя с запятой распадётся на двух испорченных получателей. В отличие от `emails->send`, здесь клиент не оборачивает одиночную строку в список, поэтому передавайте `['[email protected]']`. При создании пропущенный список сохраняется пустым. При обновлении пропущенное поле не трогает сохранённых получателей, поскольку обработчик сначала читает черновик и объединяет данные.
ccarray- Адреса Cc в той же форме, что и `to`. Если не указаны, при создании пусты, а при обновлении не меняются.
bccarray- Адреса Bcc в той же форме, что и `to`. Если не указаны, при создании пусты, а при обновлении не меняются.
subjectstring- Тема черновика, не более 998 символов, предел строки по RFC 5322. При создании по умолчанию пустая строка, а пустая тема сохраняется как `(no subject)`, поэтому у черновика тема есть всегда.
htmlstring- Тело черновика в виде разметки, не более 1 000 000 символов. Побеждает именно это тело. `html` и `text` идут в единственное поле сообщения драйвера, поэтому при отправке обоих сохраняется это.
textstring- Текстовое тело, не более 1 000 000 символов, используется только при отсутствии `html`. Черновик хранит одно тело, а не две части, поэтому переданный здесь текст при чтении черновика возвращается без преобразования в `html`.
fromstring or null- Адрес отправителя для сохранения в черновике, с отображаемым именем или без него. Если не указан при создании, у черновика нет отправителя. При обновлении, если он не указан, переносится из сохранённого черновика. Драйвер собирает всё сообщение заново из того, что ему передано, поэтому частичное изменение без этого поля молча сменило бы выбранного отправителя. Пустая строка или null при обновлении очищает его.
threadIdstring- Привязать черновик к существующей цепочке, чтобы он сохранился как ответ. Как и `from`, при обновлении, если не указан, переносится из сохранённого черновика, потому что пересборка сообщения без него оторвала бы ответ от цепочки. Пустая строка при обновлении отвязывает его. Черновик всё равно хранится как отдельная цепочка со своим идентификатором, поэтому он выводится среди черновиков, а не внутри цепочки, на которую отвечает.
Чтобы сохранить поле, не указывайте его. Передать null не то же самое. Клиент отправляет null, и каждое поле отклоняет его с 422 invalid_parameter, кроме from при обновлении, где null очищает отправителя. Пропустите массив необязательных значений через array_filter($fields, static fn(mixed $value): bool => $value !== null) перед передачей. Тело запроса тоже строгое. Поле вне этих восьми отклоняется так же, а поля для вложений нет.
Ответ: черновик (drafts->get)
objectstring- Всегда `draft`.
idstring- Идентификатор черновика: `draft-` и UUID. Записи отвечают только `object` и `id`, а не всем черновиком, поэтому берите идентификатор из результата, а не используйте повторно тот, что отправили.
toarray- Адреса получателей в том виде, в каком их сохранил черновик: голые, без отображаемых имён. Пустой список, а не null, если получателей нет.
ccarray- Адреса Cc в сохранённом виде. Пустой список, а не null, если их нет.
bccarray- Адреса Bcc в сохранённом виде. Пустой список, а не null, если их нет.
subjectstring- Сохранённая тема, никогда не null. У черновика, сохранённого без темы, она равна `(no subject)`, заглушке, которую хранит почтовый ящик, поэтому сравнивайте с ней, а не проверяйте на пустую строку.
htmlstring- Сохранённое тело или пустая строка, если тела нет. Отдельного текстового поля в ответе нет, поэтому черновик, сохранённый только с `text`, возвращается здесь.
fromstring or null- Адрес, с которым был сохранён черновик. Сообщается, только пока рабочее пространство ещё может отправлять от его имени. null у черновика, сохранённого без отправителя или с адресом, которого с тех пор не стало.
threadIdstring or null- Цепочка, на которую отвечает черновик, или null для черновика, который начинает новую переписку.
attachmentsarray- Каждая запись содержит только `filename` и `contentType`, потому что вложения черновиков хранятся как имена и типы без содержимого. `update` очищает этот список.