Brouillons
`drafts.list`, `list_all`, `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")puts page.items.size, draft[:subject] 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 forme d'OpenEmail::NotFoundError, plutôt qu'un nouveau brouillon.
Les champs d'un brouillon sont des arguments nommés qui portent les noms de l'API : le fil auquel répond un brouillon est donc threadId:. Ils peuvent aussi être passés en un seul Hash. Un brouillon revient sous forme de Hash à clés Symbol : 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 next_cursor et repart sous le nom cursor:, et list_all et iterate le suivent pour vous. iterate passe chaque brouillon à un bloc, ou renvoie un Enumerator sans bloc. 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 : has_more? 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<String>- Les adresses des destinataires sous forme d'Array de Strings, et non sous les formes Hash qu'accepte `emails.send`, car cet endpoint assemble l'Array en la liste séparée par des virgules qu'attend le driver. Une String 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`, la gem n'enveloppe pas ici une String seule dans un Array : passez donc `["[email protected]"]`. À la création, un Array omis est enregistré vide. À la mise à jour, un champ omis laisse intacts les destinataires stockés, puisque le handler lit d'abord le brouillon puis fusionne.
ccArray<String>- Les adresses Cc, dans la même forme que `to`. Vide à la création si omis, et intact à la mise à jour si omis.
bccArray<String>- 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 String 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- 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 String vide ou nil à 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 String 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 nil n'est pas la même chose. La gem l'envoie, et chaque champ le refuse avec un 422 invalid_parameter, sauf from à la mise à jour, où nil efface l'expéditeur. Appelez compact sur un Hash de valeurs optionnelles avant de le passer. 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<String>- Les adresses des destinataires telles que le brouillon les a stockées, nues, sans nom d'affichage. Un Array vide, jamais nil, quand le brouillon n'en a aucune.
ccArray<String>- Les adresses Cc telles que stockées. Un Array vide, jamais nil, quand le brouillon n'en a aucune.
bccArray<String>- Les adresses Bcc telles que stockées. Un Array vide, jamais nil, quand le brouillon n'en a aucune.
subjectString- L'objet stocké, jamais nil. 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 String vide.
htmlString- Le corps stocké, ou une String 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 nil- L'adresse avec laquelle le brouillon a été enregistré, indiquée seulement tant que l'espace de travail peut encore envoyer depuis elle. nil pour un brouillon enregistré sans expéditeur ou depuis une adresse qui a disparu depuis.
threadIdString or nil- Le fil auquel répond le brouillon, ou nil pour un brouillon qui commence une nouvelle conversation.
attachmentsArray<Hash>- 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.