IMAPTransporter
La classe IMAPTransporter
vous permet de récupérer des messages à partir d'un serveur de messagerie IMAP.
Objet IMAP Transporter
Les objets IMAP Transporter sont instanciés avec la commande IMAP New transporter. Leurs propriétés et fonctions sont les suivantes :
.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée |
.addFlags( msgIDs : Collection ; keywords : Object ) : Object .addFlags( msgIDs : Text ; keywords : Object ) : Object .addFlags( msgIDs : Longint ; keywords : Object ) : Object ajoute des flags (drapeaux) aux msgIDs pour les keywords spécifiés |
.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object ajoute un mailObj à la boîte destinationBox |
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie |
.checkConnection() : Object vérifie la connexion en utilisant les informations stockées dans l'objet transporteur |
.checkConnectionDelay : Integer la durée maximale (en secondes) autorisée avant vérification de la connexion au serveur |
.connectionTimeOut : Integer le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur |
.copy( msgsIDs : Collection ; destinationBox : Text ) : Object .copy( allMsgs : Integer ; destinationBox : Text ) : Object copie les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP |
.createBox( name : Text ) : Object crée une boîte de réception avec le name passé en paramètre |
.delete( msgsIDs : Collection ) : Object .delete( allMsgs : Integer ) : Object associe le marqueur "deleted" aux messages définis dans msgsIDs ou allMsgs |
.deleteBox( name : Text ) : Object supprime définitivement la boîte de réception nommée name sur le serveur IMAP |
.expunge() : Object supprime tous les messages marqués "deleted" du serveur de messagerie IMAP. |
.getBoxInfo( { name : Text }) : Object retourne un objet boxInfo correspondant à la boîte de réception courante ou à la boîte de réception nommée name |
.getBoxList( { parameters : Object } ) : Collection retourne une collection de boîtes aux lettres décrivant toutes les boîtes aux lettres disponibles |
.getDelimiter() : Text retourne le caractère utilisé pour délimiter les niveaux de hiérarchie dans le nom de la boîte aux lettres |
.getMail( msgNumber: Integer { ; options : Object } ) : Object .getMail( msgID: Text { ; options : Object } ) : Object retourne l'objet Email correspondant au msgNumber ou msgID dans la boite de réception désignée par l'IMAP_transporter |
.getMails( ids : Collection { ; options : Object } ) : Object .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object retourne un objet contenant une collection d'objets Email |
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob retourne un BLOB avec le contenu MIME du message correspondant au msgNumber ou msgID dans la boîte de réception désignée par le IMAP_transporter |
.host : Text le nom ou l'adresse IP du serveur hôte |
.logFile : Text le chemin du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie |
.move( msgsIDs : Collection ; destinationBox : Text ) : Object .move( allMsgs : Integer ; destinationBox : Text ) : Object déplace les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP |
.numToID( startMsg : Integer ; endMsg : Integer ) : Collection convertit les numéros de séquence en identifiants uniques IMAP pour les messages de la plage séquentielle désignée par startMsg et endMsg |
.removeFlags( msgIDs : Collection ; keywords : Object ) : Object .removeFlags( msgIDs : Text ; keywords : Object ) : Object .removeFlags( msgIDs : Longint ; keywords : Object ) : Object supprime les flags (drapeaux) des msgIDs pour les keywords spécifiés |
.renameBox( currentName : Text ; newName : Text ) : Object change le nom d'une boîte de réception sur le serveur IMAP |
.port : Integer le numéro de port utilisé pour les transactions de courrier |
.searchMails( searchCriteria : Text ) : Collection recherche les messages qui correspondent aux critères de recherche searchCriteria dans la boîte aux lettres courante |
.selectBox( name : Text { ; state : Integer } ) : Object sélectionne la boîte de réception name comme boîte de réception courante |
.subscribe( name : Text ) : Object permet d'ajouter la boîte spécifiée à l'ensemble des boîtes auxquelles vous avez "souscrit" sur le serveur IMAP |
.unsubscribe( name : Text ) : Object supprime la boîte spécifiée de l'ensemble des boîtes auxquelles vous avez "souscrit" |
.user : Text le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie |
4D.IMAPTransporter.new()
4D.IMAPTransporter.new( server : Object ) : 4D.IMAPTransporter
Paramètres | Type | Description | |
---|---|---|---|
server | Object | -> | Informations sur le serveur IMAP |
Résultat | 4D.IMAPTransporter | <- | Objet transporteur IMAP |
Description
La fonction 4D.IMAPTransporter.new()
crée et retourne un nouvel objet de type 4D.IMAPTransporter
. Elle est identique à la commande IMAP New transporter
(raccourci).
.acceptUnsecureConnection
Historique
Release | Modifications |
---|---|
17 R4 | Ajout |
.acceptUnsecureConnection : Boolean
Description
La propriété .acceptUnsecureConnection
contient True si 4D est autorisé à établir une connexion non chiffrée lorsqu'une connexion chiffrée n'est pas possible.
Elle contient False si les connexions non chiffrées ne sont pas autorisées, auquel cas une erreur est retournée lorsque la connexion chiffrée n'est pas possible.
Ports sécurisés disponibles :
-
SMTP
- 465: SMTPS
- 587 ou 25 : SMTP avec mise à niveau STARTTLS si le serveur le prend en charge.
-
IMAP
- 143 : Port IMAP non chiffré
- 993 : IMAP avec mise à niveau STARTTLS si le serveur le prend en charge
-
POP3
- 110 : Port POP3 non chiffré
- 995 : POP3 avec mise à niveau STARTTLS si le serveur le prend en charge.
.addFlags()
Historique
Release | Modifications |
---|---|
20 | Prise en charge des mots-clés personnalisés (custom keywords) |
18 R6 | Ajout |
.addFlags( msgIDs : Collection ; keywords : Object ) : Object
.addFlags( msgIDs : Text ; keywords : Object ) : Object
.addFlags( msgIDs : Longint ; keywords : Object ) : Object
Paramètres | Type | Description | |
---|---|---|---|
msgIDs | Collection | -> | Collection de chaînes : IDs uniques des messages (texte) Texte : ID unique d'un message Numérique (IMAP all) : Tous les messages de la boîte sélectionnée |
keywords | Object | -> | Mots-clés de flags à ajouter |
Résultat | Object | <- | Statut de l'opération addFlags |
Description
La fonction .addFlags()
ajoute des flags (drapeaux) aux msgIDs
pour les keywords
spécifiés.
Dans le paramètre msgIDs
, vous pouvez passer soit :
- une collection contenant les IDs uniques de messages spécifiques, ou
- l'ID unique (texte) d'un seul message ou
- la constante suivante (entier long) pour tous les messages de la boîte sélectionnée :
Constante | Valeur | Commentaire |
---|---|---|
IMAP all | 1 | Sélectionner tous les messages de la boîte sélectionnée |
Le paramètre keywords
permet de définir les flags à ajouter aux msgIDs
. Vous pouvez utiliser les flags standard suivants ainsi que des flags personnalisés (la prise en charge des flags personnalisés dépend de l'implémentation du serveur) :
Propriété | Type | Description |
---|---|---|
$draft | Boolean | True pour ajouter le marqueur "draft" au message |
$seen | Boolean | True pour ajouter le marqueur "seen" au message |
$flagged | Boolean | True pour ajouter le marqueur "flagged" au message |
$answered | Boolean | True pour ajouter le marqueur "answered" au message |
$deleted | Boolean | True pour ajouter le marqueur "deleted" au message |
<custom flag> | Boolean | True pour ajouter le flag personnalisé au message |
Les noms des flags personnalisés doivent respecter cette règle : le mot-clé doit être une chaîne non sensible à la casse, excluant les caractères de contrôle et les espaces, et ne peut inclure aucun de ces caractères : ( ) { ] % * " \
- Pour qu'un mot-clé soit pris en compte, il doit être à vrai.
- L'interprétation des indicateurs de mots-clés peut varier selon le client de messagerie.
Objet retourné
La fonction retourne un objet décrivant le statut IMAP :
Propriété | Type | Description | |
---|---|---|---|
success | Boolean | Vrai si l'opération est réussie, sinon Faux | |
statusText | Text | Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D | |
errors | Collection | Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue) | |
[].errcode | Number | Code d'erreur 4D | |
[].message | Text | Description de l'erreur 4D | |
[].componentSignature | Text | Signature du composant interne qui a retourné l'erreur |
Exemple
var $options;$transporter;$boxInfo;$status : Object
$options:=New object
$options.host:="imap.gmail.com"
$options.port:=993
$options.user:="4d@gmail.com"
$options.password:="xxxxx"
// Créer transporteur
$transporter:=IMAP New transporter($options)
// Sélectionner la boîte de messagerie
$boxInfo:=$transporter.selectBox("INBOX")
// Marquer tous les messages de la boite de réception (INBOX) comme étant lus/vus
$flags:=New object
$flags["$seen"]:=True
$status:=$transporter.addFlags(IMAP all;$flags)
.append()
Historique
Release | Modifications |
---|---|
18 R6 | Ajout |
.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object
Paramètres | Type | Description | |
---|---|---|---|
mailObj | Object | -> | Objet email |
destinationBox | Text | -> | Mailbox devant recevoir l'objet email |
options | Object | -> | Objet contenant les informations de charset |
Résultat | Object | <- | Statut de l'opération |
Description
La fonction .append()
ajoute un mailObj
à la boîte destinationBox
.
Dans le paramètre mailObj
, passez un objet email. Pour une description détaillée des propriétés de mail, reportez-vous à Objet Email. La fonction .append()
prend en charge les marqueurs de mots-clés dans l'attribut keywords
des objets email.
Le paramètre optionnel destinationBox
vous permet de passer le nom de la boîte de réception dans laquelle l'objet mailObj
sera ajouté. S'il est omis, la mailbox courante sera utilisée.
Dans le paramètre optionnel options
, vous pouvez passer un objet permettant de définir le charset et l'encodage des différentes parties de l'email. Propriétés disponibles :
Propriété | Type | Description |
---|---|---|
headerCharset | Text | Charset et encodage utilisés pour les parties de mail suivantes : le sujet, les noms de fichiers joints et le nom du mail. Valeurs possibles : voir le tableau des charsets possibles |
bodyCharset | Text | Charset et encodage utilisés pour le contenu html et le texte du body du mail. Valeurs possibles : voir le tableau des charsets possibles |
Charsets possibles :
Constante | Valeur | Commentaire |
---|---|---|
mail mode ISO2022JP | US-ASCII_ISO-2022-JP_UTF8_QP |
|
mail mode ISO88591 | ISO-8859-1 |
|
mail mode UTF8 | US-ASCII_UTF8_QP | headerCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut) |
mail mode UTF8 in base64 | US-ASCII_UTF8_B64 | headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64 |
Objet retourné
La fonction retourne un objet décrivant le statut IMAP :
Propriété | Type | Description | |
---|---|---|---|
success | Boolean | Vrai si l'opération est réussie, sinon Faux | |
statusText | Text | Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D | |
errors | Collection | Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue) | |
[].errcode | Number | Code d'erreur 4D | |
[].message | Text | Description de l'erreur 4D | |
[].componentSignature | Text | Signature du composant interne qui a retourné l'erreur |
Exemple
Pour enregistrer un email dans la boîte Drafts :
var $settings; $status; $msg; $imap: Object
$settings:=New object("host"; "domain.com"; "user"; "xxxx"; "password"; "xxxx"; "port"; 993)
$imap:=IMAP New transporter($settings)
$msg:=New object
$msg.from:="xxxx@domain.com"
$msg.subject:="Lorem Ipsum"
$msg.textBody:="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
$msg.keywords:=New object
$msg.keywords["$seen"]:=True //marquer le message comme étant lu
$msg.keywords["$draft"]:=True //marquer le message comme brouillon
$status:=$imap.append($msg; "Drafts")
.authenticationMode
Historique
Release | Modifications |
---|---|
17 R4 | Ajout |
.authenticationMode : Text
Description
La propriété .authenticationMode
contient le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie.
Par défaut, le mode le plus sécurisé pris en charge par le serveur est utilisé.
Valeurs possibles :
Valeur | Constantes | Commentaire |
---|---|---|
CRAM-MD5 | IMAP authentication CRAM MD5 | Authentification à l'aide du protocole CRAM-MD5 |
LOGIN | IMAP authentication login | Authentification à l'aide du protocole LOGIN |
OAUTH2 | IMAP authentication OAUTH2 | Authentification à l'aide du protocole OAuth2 |
PLAIN | IMAP authentication plain | Authentification à l'aide du protocole PLAIN |
.checkConnection()
Historique
Release | Modifications |
---|---|
17 R4 | Ajout |
.checkConnection() : Object
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Object | <- | Statut de la connexion de l'objet transporteur |
Description
La fonction .checkConnection()
vérifie la connexion en utilisant les informations stockées dans l'objet transporteur, recrée la connexion si nécessaire et renvoie le statut. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.
Objet retourné
La fonction envoie une requête au serveur de mail et retourne un objet décrivant le statut. Cet objet peut avoir les propriétés suivantes :
Propriété | Type | Description | |
---|---|---|---|
success | boolean | Vrai si la vérification a été effectuée avec succès, sinon Faux | |
status | number | (SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail) | |
statusText | text | Message du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D | |
errors | collection | Pile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue) | |
[ ].errCode | number | Code d'erreur 4D | |
[ ].message | text | Description de l'erreur 4D | |
[ ].componentSignature | text | Signature du composant interne qui a retourné l'erreur |
.checkConnectionDelay
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.checkConnectionDelay : Integer
Description
La propriété .checkConnectionDelay
contient la durée maximale (en secondes) autorisée avant vérification de la connexion au serveur. Si cette durée est dépassée entre deux appels de méthodes, la connexion au serveur sera vérifiée. Par défaut, si la propriété n'a pas été définie dans l'objet server, la valeur est de 300.
Attention : Assurez-vous que le timeout défini est inférieur au timeout du serveur, sinon le timeout du client sera inutile.
.connectionTimeOut
Historique
Release | Modifications |
---|---|
17 R5 | Ajout |
.connectionTimeOut : Integer
Description
La propriété .connectionTimeOut
contient le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur. Par défaut, si la propriété n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter
, POP3 New transporter
, IMAP New transporter
), la valeur utilisée est 30.
.copy()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.copy( msgsIDs : Collection ; destinationBox : Text ) : Object
.copy( allMsgs : Integer ; destinationBox : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
msgsIDs | Collection | -> | Collection d'IDs uniques de messages (texte) |
allMsgs | Integer | -> | IMAP all : tous les messages de la boîte de réception sélectionnée |
destinationBox | Text | -> | Boîte de réception recevant les messages copiés |
Résultat | Object | <- | Statut de l'opération de copie |
Description
La fonction .copy()
copie les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP.
Vous pouvez passer :
- dans le paramètre msgsIDs, une collection contenant les ID uniques des messages spécifiques à copier, ou
- dans le paramètre allMsgs, la constante
IMAP all
(integer) pour copier tous les messages de la boîte de réception sélectionnée.
Le paramètre destinationBox vous permet de passer une valeur texte avec le nom de la boîte de réception dans laquelle seront placés les messages copiés.
Objet retourné
La fonction retourne un objet décrivant le statut IMAP :
Propriété | Type | Description | |
---|---|---|---|
success | Boolean | Vrai si l'opération est réussie, sinon Faux | |
statusText | Text | Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D | |
errors | Collection | Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue) | |
[].errcode | Number | Code d'erreur 4D | |
[].message | Text | Description de l'erreur 4D | |
[].componentSignature | Text | Signature du composant interne qui a retourné l'erreur |
Exemple 1
Pour copier une sélection de messages :
var $server;$boxInfo;$status : Object
var $mailIds : Collection
var $transporter : 4D.IMAPTransporter
$server:=New object
$server.host:="imap.gmail.com" //Obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$transporter:=IMAP New transporter($server)
//sélectionner la boite de réception
$boxInfo:=$transporter.selectBox("inbox")
//obtenir la collection des IDs uniques de message
$mailIds:=$transporter.searchMails("subject \"4D new feature:\"")
// copier les messages identifiés dans la boîte de réception "documents"
$status:=$transporter.copy($mailIds;"documents")
Exemple 2
Pour copier tous les messages de la boîte de réception courante :
var $server;$boxInfo;$status : Object
var $transporter : 4D.IMAPTransporter
$server:=New object
$server.host:="imap.gmail.com" //Obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$transporter:=IMAP New transporter($server)
//sélectionner la boite de réception
$boxInfo:=$transporter.selectBox("inbox")
// copier les messages dans la boîte de réception "documents"
$status:=$transporter.copy(IMAP all;"documents")
.createBox()
Historique
Release | Modifications |
---|---|
19 | Ajout |
.createBox( name : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la nouvelle mailbox |
Résultat | Object | <- | Statut de l'opération de création de mailbox |
Description
La fonction .createBox()
crée une boîte de réception avec le name
passé en paramètre. Si le caractère séparateur de hiérarchie du serveur IMAP apparaît dans le nom de la mailbox, le serveur IMAP créera tous les boîtes parentes nécessaires pour créer la boîte donnée.
Par exemple, si vous essayez de créer "Projects/IMAP/Doc" dans un serveur dont le "/" est le caractère séparateur de hiérarchie, les éléments suivants seront créés :
- Uniquement la boîte "Doc" si "Projects" & "IMAP" existent déjà.
- Les boîtes "IMAP" & "Doc" si seule “Projects” existe déjà.
- Les boîtes "Projects" & “IMAP” & "Doc" si elles n'existent pas déjà.
Dans le paramètre name
, passez le nom de la mailbox à créer.
Objet retourné
La fonction retourne un objet décrivant le statut IMAP :
Propriété | Type | Description | |
---|---|---|---|
success | Boolean | Vrai si l'opération est réussie, sinon Faux | |
statusText | Text | Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D | |
errors | Collection | Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue) | |
[].errcode | Number | Code d'erreur 4D | |
[].message | Text | Description de l'erreur 4D | |
[].componentSignature | Text | Signature du composant interne qui a retourné l'erreur |
Exemple
Pour créer une nouvelle boîte “Invoices” :
var $pw : text
var $options; $transporter; $status : object
$options:=New object
$pw:=Request("Please enter your password:")
If(OK=1)
$options.host:="imap.gmail.com"
$options.user:="test@gmail.com"
$options.password:=$pw
$transporter:=IMAP New transporter($options)
$status:=$transporter.createBox("Invoices")
If ($status.success)
ALERT("Mailbox creation successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if