`$mail.read`¶

Description¶

Lit une boîte e-mail.

La méthode permet de renseigner les paramètres du serveur d'e-mail de différentes manières:

soit en passant un nom de mailbox défini dans le config
soit en passant explicitement les paramètres de connexion type, host, port et éventuellement security
soit en définissant les properties explicitement; dans ce cas, veuillez vous reporter à la documentation de javamail pour connaître les propriétés à définir

Syntaxe¶

$mail.read( options )

Paramètres¶

options map

Map pouvant contenir les options suivantes:

mailbox string

Nom de la mailbox à utiliser. Fait référence à un name d'entrée email.mailbox du config.

type string

Type de boîte mail. Les types reconnus sont "pop3", "pop3s", "imap" et "imaps".

host string

URL du host à utiliser (si défini, prime sur les autres valeurs de host)

port number

Port du serveur smtp à utiliser (si défini, prime sur les autres valeurs de port)

username string

Nom d'utilisateur pour l'authentification sur le serveur smtp (si défini, prime sur le username défini ailleurs)

password string

Mot de passe à utiliser pour l'authentification sur le serveur smtp (si défini, prime sur le password défini ailleurs)

security string

Type de sécurité. Peut prendre une des valeurs "none", "starttls" ou "ssl" (ce dernier est mis pour le mode "ssl/tls")

properties map

Map de propriété à passer à la session. Cette option permet de passer tous les paramètres de connexion (p.ex "mail.pop3.host", "mail.pop3.port", "mail.pop3.starttls.enable", etc.) ainsi que des propriétés supplémentaires (p.ex "mail.debug", "mail.imap.timeout", "mail.pop3.timeout", etc.).

La liste exhaustive des propriétés est disponible sur les pages https://javaee.github.io/javamail/docs/api/com/sun/mail/imap/package-summary.html et https://javaee.github.io/javamail/docs/api/com/sun/mail/pop3/package-summary.html.

Les propriétés définies via cette option priment sur celles équivalentes définies par la méthode. Par exemple, le fait de spécifier une propriété "mail.imap.ssl.host" prime sur le host défini au niveau de la section mailbox référencée ou via la propriété host.

folder string

Nom du dossier à lire (par défaut: "INBOX")

setFlags array / string

Liste de flags à définir sur les messages lus. La valeur attendue est soit un tableau, soit une comma-separated list pouvant contenir les flags suivants: seen, flagged, answered, deleted, draft, recent, user. Il est possible d'utiliser des flags personnalisés, mais il se peut que le serveur d'e-mail ne supporte pas l'usage de tels flags.

ignoreFlags array / string

Liste de flags à utiliser comme filtre. Les messages ayant l'un des flags énumérés de la liste ne sont pas lus. La valeur attendue est soit un tableau, soit une comma-separated list pouvant contenir les flags suivant: seen, flagged, answered, deleted, draft, recent, user. Il est possible d'utiliser des flags personnalisés, mais il est se peut que le serveur e-mail ne supporte pas l'usage de tels flags.

Notez que les flags ne sont utilisables qu'en imap. Le filtre est sans effet sur une session pop3.

fetchProfile array / string

Liste d'éléments à récupérer. Par défaut la méthode récupère toutes les parties des messages, mais pour des raisons de performances il est possible d'indiquer à la méthode de ne récupérer qu'une partie des éléments, par exemple uniquement l'enveloppe sans le contenu. La valeur attendue est soit un tableau, soit une comma-separated list pouvant contenir les éléments suivants: enveloppe, contentinfo, flags, size ainsi que n'importe quel nom de header à récupérer du message (p.ex X-mailer).

getContent boolean

Flag true/false indiquant si on souhaite récupérer le contenu du message (par défaut: false).

Lorsque le flag est activé, la méthode essaie de récupérer le contenu aux formats "text" et "html". L'objet de retour de la méthode contiendra donc une propriété content qui est un map contenant ces deux types de contenus (text et html).

fixInlineImages boolean

Ce flag true/false demande à la méthode d'effectuer un travail de substitution des références d'images. Concrètement, la méthode va tenter de remplacer les références d'éléments inline du genre:

<img src="cid:part1.FdL0aOTi.xgazc0GI@somedomain.com">

par une version base64 de l'image. Dans le cas ci-dessus, l'élément serait changé en

<img src="data:image/png;base64,iVBORw0KGgoAAAANS...">

getInlines boolean

Flag true/false indiquant si on souhaite récupérer séparément les objets inline. Les objets sont retournés sous forme d'un map, avec le cid utilisé comme clé.

Par défaut: false

getAttachments boolean

Flag true/false indiquant si on souhaite récupérer les éventuelles pièces jointes (par défaut: false).

cleanHistory boolean

Ce flag true/false demande à la méthode de ne pas reprendre le contenu historisé. Concrètement, la méthode ignore les lignes qui débutent par ">" sur le contenu "text" ainsi que les éléments "blockquote" du contenu "html".

firstNum number

Numéro du premier message à récupérer. firstNum et lastNum permettent de récupérer les messages par blocs. Les deux paramètres sont numérotés à partir de 1.

lastNum number

Numéro du dernier message à récupérer. firstNum et lastNum permettent de récupérer les messages par blocs. Les deux paramètres sont numérotés à partir de 1. Si le paramètre vaut 0, cela signifie qu'on veut uniquement faire un test de connexion, sans récupérer de message.

Retour¶

Retourne un tableau d'objets contenant les e-mails lus du serveur. Dans la version actuelle, les e-mails sont triés selon la date d'envoi (croissante).

Voici un exemple de map reprenant les données reçues pour un e-mail:

{
    "cc": [],
    "bcc": [],
    "attachments": [
        /path-to/44c1e4e4-8265-4ca1-ab84-3a5ca415e190,
        /path-to/3b112a9f-4226-471f-a0bb-907979964d83
    ],
    "subject": Example,
    "num": 1,
    "flags": [$HasAttachment],
    "content": {
        "html": <null>,
        "text": Voir pièce jointe
    },
    "sentDate": 2025-04-14 11:29:02,
    "size": 51753,
    "replyTo": *******,
    "from": *******,
    "to": [*******],
    "inlines": {},
    "contentType": multipart/mixed; 
    boundary=------------RyY8go3aObtj0G480ut0yZZV
}

Exemple¶

for (var msg : $mail.read({
                   type: params[1],
                   host: params[2],
                   port: params[3],
                   username: params[4],
                   password: params[5],
                   security: params[6],
                   ignoreFlags: [ "seen", "answered" ],
                   setFlags: [ "answered" ] })) {
    $logger.warn("${msg.from}\t${msg.subject}");
    ...
}

$mail.read¶