Rascunhos
`drafts->list`, `listAll`, `iterate`, `get`, `create`, `update` e `delete`.
Todos os métodos
$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 mantém o id do rascunho, pelo que o valor com que responde é sempre o que passou. Um id desconhecido dá 404, lançado como NotFoundException, em vez de criar um novo rascunho.
Os campos de um rascunho são as chaves de um único array com os nomes da API, por isso a conversa a que um rascunho responde é threadId. Um rascunho volta como um array com chaves em camelCase, por isso $draft['subject'] lê o assunto. Cada escrita responde apenas com object e id, por isso leia o rascunho completo com get.
list pagina da mesma forma que threads->list. O pageToken da API volta como nextCursor e é passado como cursor:, e listAll e iterate seguem-no por si. iterate devolve um Generator que entrega um rascunho de cada vez. Uma página contém 25 rascunhos, a menos que limit: peça até 100. query: aceita a sintaxe de pesquisa de threads->list, e a pesquisa nunca sai dos rascunhos. Uma linha é apenas object e id, por isso chame get para obter os destinatários, o assunto e o corpo.
A lista de rascunhos não indica hasMore, por isso hasMore é true sempre que vem um cursor. O servidor oferece um sempre que uma página está cheia, por isso uma última página que por acaso esteja cheia é seguida de uma página vazia.
Um rascunho é guardado como uma conversa com a etiqueta DRAFT, e é por isso que $client->threads->list(folder: 'draft') lista os mesmos rascunhos. get, update e delete respondem a um id de conversa normal com um 404, embora threads->get o abra. delete remove um rascunho de vez. Não vai para o Lixo e não há forma de anular.
Para enviar um rascunho, passe o seu id a emails->send como draftId. O rascunho fornece o conteúdo e o envio fornece o envelope. Um rascunho não pode ser combinado com template nem com translate.
$client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'draftId' => 'draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8',]);Parâmetros: drafts->create e drafts->update
toarray- Endereços dos destinatários como uma lista de strings, e não nas formas de array que `emails->send` aceita, porque este endpoint junta a lista na string separada por vírgulas que o driver espera. Uma string pode levar um nome de apresentação, como em `Ada Lovelace <[email protected]>`, mas um nome que contenha uma vírgula divide-se em dois destinatários inválidos. Ao contrário de `emails->send`, aqui o cliente não envolve uma string isolada numa lista, por isso passe `['[email protected]']`. Na criação, uma lista omitida é guardada vazia. Na atualização, um campo omitido deixa os destinatários guardados intactos, já que o handler lê primeiro o rascunho e depois faz a junção.
ccarray- Endereços em Cc, na mesma forma que `to`. Vazio na criação quando omitido, e inalterado na atualização quando omitido.
bccarray- Endereços em Bcc, na mesma forma que `to`. Vazio na criação quando omitido, e inalterado na atualização quando omitido.
subjectstring- O assunto do rascunho, com no máximo 998 caracteres, o limite de linha do RFC 5322. Na criação, a predefinição é uma string vazia, e um assunto vazio é guardado como `(no subject)`, pelo que um rascunho tem sempre um.
htmlstring- O corpo do rascunho em markup, com no máximo 1 000 000 caracteres. É este o corpo que prevalece. `html` e `text` alimentam o campo de mensagem único do driver, pelo que enviar ambos guarda este.
textstring- Um corpo em texto simples, com no máximo 1 000 000 caracteres, usado apenas quando `html` está ausente. O rascunho guarda um único corpo em vez de duas partes, pelo que o texto fornecido aqui é devolvido sem conversão em `html` quando o rascunho é lido.
fromstring or null- O endereço do remetente a guardar no rascunho, com ou sem nome de apresentação. Se for omitido na criação, o rascunho não tem remetente. Na atualização, quando omitido, é mantido a partir do rascunho guardado. O driver reconstrói a mensagem inteira a partir do que recebe, pelo que uma atualização parcial que o omitisse alteraria silenciosamente o remetente escolhido. Uma string vazia ou null na atualização apaga-o.
threadIdstring- Associa o rascunho a uma conversa existente para que seja guardado como resposta. Tal como `from`, é mantido na atualização quando omitido, porque reconstruir a mensagem sem ele separaria a resposta da sua conversa. Uma string vazia na atualização desassocia-o. O rascunho continua a ser guardado como uma conversa própria com o seu próprio id, por isso é listado com os rascunhos e não dentro da conversa a que responde.
Omita um campo para o manter. Passar null não é o mesmo. O cliente envia-o, e todos os campos o recusam com um 422 invalid_parameter exceto from na atualização, onde null apaga o remetente. Passe um array de valores opcionais por array_filter($fields, static fn(mixed $value): bool => $value !== null) antes de o enviar. O corpo também é estrito. Um campo fora destes oito é recusado da mesma forma, e não há nenhum campo para anexos.
Resposta: um rascunho (drafts->get)
objectstring- Sempre `draft`.
idstring- O id do rascunho, `draft-` seguido de um UUID. As escritas respondem apenas com `object` e `id` em vez de um rascunho completo, por isso leia o id do resultado em vez de reutilizar o que enviou.
toarray- Os endereços dos destinatários tal como o rascunho os guardou, simples, sem qualquer nome de apresentação. Uma lista vazia, nunca null, quando o rascunho não tem nenhum.
ccarray- Endereços em Cc tal como foram guardados. Uma lista vazia, nunca null, quando o rascunho não tem nenhum.
bccarray- Endereços em Bcc tal como foram guardados. Uma lista vazia, nunca null, quando o rascunho não tem nenhum.
subjectstring- O assunto guardado, nunca null. Um rascunho guardado sem assunto mostra `(no subject)`, o marcador que a caixa de correio guarda, por isso compare com isso em vez de verificar se há uma string vazia.
htmlstring- O corpo guardado, ou uma string vazia quando o rascunho não tem nenhum. Não existe um campo de texto separado na resposta, por isso um rascunho guardado apenas com `text` é devolvido aqui.
fromstring or null- O endereço com que o rascunho foi guardado, indicado apenas enquanto o espaço de trabalho ainda puder enviar a partir dele. É null para um rascunho guardado sem remetente ou a partir de um endereço que entretanto deixou de existir.
threadIdstring or null- A conversa a que o rascunho responde, ou null para um rascunho que inicia uma nova conversa.
attachmentsarray- Cada entrada tem apenas `filename` e `contentType`, porque os anexos dos rascunhos são guardados como nomes e tipos sem conteúdo. Um `update` esvazia esta lista.