Brouillons
`drafts->list`, `listAll`, `iterate`, `get`, `create`, `update` et `delete`.
Toutes les méthodes
$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 conserve l'id du brouillon : la valeur qu'il renvoie est donc toujours celle que vous avez transmise. Un id inconnu donne un 404, levé sous la forme d'une NotFoundException, plutôt qu'un nouveau brouillon.
Les champs d'un brouillon sont les clés d'un tableau aux noms de l'API : le fil auquel répond un brouillon est donc threadId. Un brouillon revient sous forme de tableau à clés en camelCase : $draft['subject'] lit donc l'objet. Chaque écriture ne répond qu'avec object et id : lisez donc le brouillon complet avec get.
list pagine comme threads->list. Le pageToken de l'API revient sous le nom nextCursor et repart sous le nom cursor:, et listAll et iterate le suivent pour vous. iterate renvoie un Generator qui fournit les brouillons un par un. Une page contient 25 brouillons, sauf si limit: en demande jusqu'à 100. query: prend la syntaxe de recherche de threads->list, et la recherche ne sort jamais des brouillons. Une ligne n'est faite que d'object et d'id : appelez donc get pour les destinataires, l'objet et le corps.
La liste des brouillons n'indique pas de hasMore : hasMore vaut donc true dès qu'un curseur est revenu. Le serveur en propose un chaque fois qu'une page est pleine : une dernière page qui se trouve être pleine est donc suivie d'une page vide.
Un brouillon est stocké comme un fil portant le libellé DRAFT, c'est pourquoi $client->threads->list(folder: 'draft') liste les mêmes brouillons. get, update et delete répondent par un 404 à un id de fil ordinaire, même si threads->get l'ouvre. delete supprime un brouillon définitivement. Il ne passe pas par la corbeille et il n'y a pas d'annulation possible.
Pour envoyer un brouillon, passez son id à emails->send comme draftId. Le brouillon fournit le contenu et l'envoi fournit l'enveloppe. Un brouillon ne peut pas être combiné avec template ou translate.
$client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'draftId' => 'draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8',]);Paramètres : drafts->create et drafts->update
toarray- Les adresses des destinataires sous forme de liste de chaînes, et non sous les formes de tableau qu'accepte `emails->send`, car cet endpoint assemble la liste en la chaîne séparée par des virgules qu'attend le driver. Une chaîne peut porter un nom d'affichage, comme dans `Ada Lovelace <[email protected]>`, mais un nom qui contient une virgule se scinde en deux destinataires cassés. Contrairement à `emails->send`, le client n'enveloppe pas ici une chaîne seule dans une liste : passez donc `['[email protected]']`. À la création, une liste omise est enregistrée vide. À la mise à jour, un champ omis laisse intacts les destinataires stockés, puisque le handler lit d'abord le brouillon puis fusionne.
ccarray- Les adresses Cc, dans la même forme que `to`. Vide à la création si omis, et intact à la mise à jour si omis.
bccarray- Les adresses Bcc, dans la même forme que `to`. Vide à la création si omis, et intact à la mise à jour si omis.
subjectstring- L'objet du brouillon, 998 caractères au maximum, la limite de ligne de la RFC 5322. À la création, il vaut par défaut une chaîne vide, et un objet vide est stocké sous la forme `(no subject)` : un brouillon en a donc toujours un.
htmlstring- Le corps du brouillon sous forme de balisage, 1 000 000 de caractères au maximum. C'est le corps qui l'emporte. `html` et `text` alimentent l'unique champ de message du driver : envoyer les deux enregistre donc celui-ci.
textstring- Un corps en texte brut, 1 000 000 de caractères au maximum, utilisé uniquement en l'absence de `html`. Le brouillon stocke un seul corps plutôt que deux parties : le texte fourni ici revient donc sans conversion sur `html` à la lecture du brouillon.
fromstring or null- L'adresse d'expédition à enregistrer sur le brouillon, avec ou sans nom d'affichage. Omise à la création, le brouillon n'a pas d'expéditeur. À la mise à jour, elle est reprise du brouillon stocké si elle est omise. Le driver reconstruit tout le message à partir de ce qu'on lui transmet : un patch partiel qui l'omettrait changerait donc silencieusement l'expéditeur choisi. Une chaîne vide ou null à la mise à jour l'efface.
threadIdstring- Rattache le brouillon à un fil existant pour qu'il soit enregistré comme une réponse. Comme `from`, il est repris à la mise à jour s'il est omis, car reconstruire le message sans lui détacherait la réponse de son fil. Une chaîne vide à la mise à jour le détache. Le brouillon reste stocké comme un fil à part entière sous son propre id : il est donc listé avec les brouillons plutôt qu'à l'intérieur du fil auquel il répond.
Omettez un champ pour le conserver. Passer null n'est pas la même chose. Le client l'envoie, et chaque champ le refuse avec un 422 invalid_parameter, sauf from à la mise à jour, où null efface l'expéditeur. Faites passer un tableau de valeurs optionnelles par array_filter($fields, static fn(mixed $value): bool => $value !== null) avant de le transmettre. Le corps est strict lui aussi. Un champ hors de ces huit est refusé de la même façon, et il n'y a pas de champ pour les pièces jointes.
Réponse : un brouillon (drafts->get)
objectstring- Toujours `draft`.
idstring- L'id du brouillon, `draft-` suivi d'un UUID. Les écritures ne répondent qu'avec `object` et `id` plutôt qu'avec un brouillon complet : lisez donc l'id sur le résultat au lieu de réutiliser celui que vous avez envoyé.
toarray- Les adresses des destinataires telles que le brouillon les a stockées, nues, sans nom d'affichage. Une liste vide, jamais null, quand le brouillon n'en a aucune.
ccarray- Les adresses Cc telles que stockées. Une liste vide, jamais null, quand le brouillon n'en a aucune.
bccarray- Les adresses Bcc telles que stockées. Une liste vide, jamais null, quand le brouillon n'en a aucune.
subjectstring- L'objet stocké, jamais null. Un brouillon enregistré sans objet affiche `(no subject)`, le texte de substitution que stocke la boîte : comparez donc avec cette valeur plutôt que de tester une chaîne vide.
htmlstring- Le corps stocké, ou une chaîne vide quand le brouillon n'en a pas. Il n'existe pas de champ texte distinct en sortie : un brouillon enregistré avec `text` seul est donc renvoyé ici.
fromstring or null- L'adresse avec laquelle le brouillon a été enregistré, indiquée seulement tant que l'espace de travail peut encore envoyer depuis elle. null pour un brouillon enregistré sans expéditeur ou depuis une adresse qui a disparu depuis.
threadIdstring or null- Le fil auquel répond le brouillon, ou null pour un brouillon qui commence une nouvelle conversation.
attachmentsarray- Chaque entrée n'a que `filename` et `contentType`, car les pièces jointes des brouillons sont stockées sous forme de noms et de types sans contenu. Un `update` vide cette liste.