Borradores
`drafts->list`, `listAll`, `iterate`, `get`, `create`, `update` y `delete`.
Todos los 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 conserva el id del borrador, así que el valor con el que responde es siempre el que pasaste. Un id desconocido es un 404, lanzado como NotFoundException, y no un borrador nuevo.
Los campos de un borrador son las claves de un array con los nombres de la API, así que el hilo al que responde un borrador es threadId. Un borrador vuelve como un array con claves en camelCase, así que $draft['subject'] lee el asunto. Cada escritura responde solo con object e id, así que lee el borrador completo con get.
list pagina igual que threads->list. El pageToken de la API vuelve como nextCursor y se pasa como cursor:, y listAll e iterate lo siguen por ti. iterate devuelve un Generator que entrega los borradores de uno en uno. Una página contiene 25 borradores salvo que limit: pida hasta 100. query: acepta la sintaxis de búsqueda de threads->list, y la búsqueda nunca sale de los borradores. Una fila es solo object e id, así que llama a get para obtener los destinatarios, el asunto y el cuerpo.
La lista de borradores no indica hasMore, así que hasMore es true siempre que vuelve un cursor. El servidor ofrece uno siempre que una página está llena, así que una última página que resulte estar llena va seguida de una página vacía.
Un borrador se guarda como un hilo con la etiqueta DRAFT, y por eso $client->threads->list(folder: 'draft') lista los mismos borradores. get, update y delete responden a un id de hilo normal con un 404, aunque threads->get lo abra. delete elimina un borrador para siempre. No va a la papelera y no se puede deshacer.
Para enviar un borrador, pasa su id a emails->send como draftId. El borrador aporta el contenido y el envío aporta el sobre. Un borrador no se puede combinar con template ni con translate.
$client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'draftId' => 'draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8',]);Parámetros: drafts->create y drafts->update
toarray- Direcciones de destinatarios como una lista de cadenas, no las formas de array que acepta `emails->send`, porque este endpoint une la lista en la cadena separada por comas que quiere el driver. Una cadena puede llevar un nombre visible, como en `Ada Lovelace <[email protected]>`, pero un nombre que contiene una coma se parte en dos destinatarios rotos. A diferencia de `emails->send`, aquí el cliente no envuelve una cadena suelta en una lista, así que pasa `['[email protected]']`. Al crear, una lista omitida se guarda vacía. Al actualizar, un campo omitido deja intactos los destinatarios almacenados, ya que el handler lee primero el borrador y fusiona.
ccarray- Direcciones en Cc, en la misma forma que `to`. Vacío al crear si se omite, e intacto al actualizar si se omite.
bccarray- Direcciones en Bcc, en la misma forma que `to`. Vacío al crear si se omite, e intacto al actualizar si se omite.
subjectstring- El asunto del borrador, de 998 caracteres como máximo, el límite de línea de RFC 5322. Al crear, por defecto es una cadena vacía, y un asunto vacío se guarda como `(no subject)`, así que un borrador siempre tiene uno.
htmlstring- El cuerpo del borrador como marcado, de 1.000.000 de caracteres como máximo. Es el cuerpo que gana. `html` y `text` alimentan el único campo de mensaje del driver, así que enviar ambos guarda este.
textstring- Un cuerpo de texto plano, de 1.000.000 de caracteres como máximo, que solo se usa cuando falta `html`. El borrador guarda un único cuerpo en lugar de dos partes, así que el texto que pongas aquí vuelve sin convertir en `html` cuando se lee el borrador.
fromstring or null- La dirección del remitente que se guarda en el borrador, con o sin nombre visible. Si se omite al crear, el borrador no tiene remitente. Al actualizar, se arrastra desde el borrador almacenado si se omite. El driver reconstruye el mensaje entero a partir de lo que recibe, así que un parche parcial que la descartara cambiaría en silencio el remitente elegido. Una cadena vacía o null al actualizar la borra.
threadIdstring- Adjunta el borrador a un hilo existente para que se guarde como respuesta. Igual que `from`, se arrastra al actualizar si se omite, porque reconstruir el mensaje sin él desvincularía la respuesta de su hilo. Una cadena vacía al actualizar lo desvincula. El borrador se sigue guardando como un hilo propio con su propio id, así que se lista con los borradores y no dentro del hilo al que responde.
Omite un campo para conservarlo. Pasar null no es lo mismo. El cliente lo envía, y todos los campos lo rechazan con un 422 invalid_parameter salvo from al actualizar, donde null borra el remitente. Pasa un array de valores opcionales por array_filter($fields, static fn(mixed $value): bool => $value !== null) antes de enviarlo. El cuerpo también es estricto. Un campo fuera de estos ocho se rechaza de la misma forma, y no hay ningún campo para adjuntos.
Respuesta: un borrador (drafts->get)
objectstring- Siempre `draft`.
idstring- El id del borrador, `draft-` seguido de un UUID. Las escrituras responden solo con `object` e `id` en lugar de un borrador completo, así que lee el id del resultado en vez de reutilizar el que enviaste.
toarray- Las direcciones de los destinatarios tal como las guardó el borrador, escuetas, sin ningún nombre visible. Una lista vacía, nunca null, cuando el borrador no tiene ninguna.
ccarray- Direcciones en Cc tal como están guardadas. Una lista vacía, nunca null, cuando el borrador no tiene ninguna.
bccarray- Direcciones en Bcc tal como están guardadas. Una lista vacía, nunca null, cuando el borrador no tiene ninguna.
subjectstring- El asunto guardado, nunca null. Un borrador guardado sin asunto muestra `(no subject)`, el marcador que guarda el buzón, así que compara con eso en lugar de comprobar si hay una cadena vacía.
htmlstring- El cuerpo guardado, o una cadena vacía cuando el borrador no tiene ninguno. No hay un campo de texto aparte en la salida, así que un borrador guardado solo con `text` se devuelve aquí.
fromstring or null- La dirección con la que se guardó el borrador, que solo se indica mientras el espacio de trabajo pueda seguir enviando con ella. Es null para un borrador guardado sin remitente o desde una dirección que ya no existe.
threadIdstring or null- El hilo al que responde el borrador, o null para un borrador que inicia una conversación nueva.
attachmentsarray- Cada entrada tiene solo `filename` y `contentType`, porque los adjuntos de los borradores se guardan como nombres y tipos sin contenido. Un `update` vacía esta lista.