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 objet 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 à l'aide des 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 maximal (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 dans la destinationBox sur le serveur IMAP |
.createBox( name : Text ) : Object crée une mailbox avec le name passé en paramètre |
.delete( msgsIDs : Collection ) : Object .delete( allMsgs : Integer ) : Object associe le marqueur "deleted" aux messages désignés par 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 renvoie un objet boxInfo correspondant à la maibox courante ou à la mailbox nommée name |
.getBoxList( { parameters : Object } ) : Collection renvoie une collection de boîtes aux lettres décrivant toutes les boîtes aux lettres disponibles |
.getDelimiter() : Text renvoie 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 renvoie l'objet Email correspondant au msgNumber ou msgID dans la boîte aux lettres désignée par IMAP_transporter |
.getMails( ids : Collection { ; options : Object } ) : Object .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object renvoie un objet contenant une collection d'objets Email |
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob copie les messages définis par msgsIDs ou allMsgs dans la destinationBox sur le serveur IMAP |
.host : Text le nom ou l'adresse IP du serveur hôte |
.logFile : Text le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion |
.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 des msgIDs pour les keywords spécifiés |
.renameBox( currentName : Text ; newName : Text ) : Object change le nom d'une boîte aux lettres sur le serveur IMAP |
.port : Integer le numéro de port utilisé pour les transactions d'emails |
.searchMails( searchCriteria : Text ) : Collection recherche les messages qui correspondent aux critères de recherche searchCriteria dans la boîte de réception courante |
.selectBox( name : Text { ; state : Integer } ) : Object sélectionne la mailbox name comme boîte aux lettres courante |
.subscribe( name : Text ) : Object permet d'ajouter la boîte aux lettres spécifiée à l'ensemble des mailboxes auxquelles vous avez "souscrit" sur le serveur IMAP |
.unsubscribe( name : Text ) : Object supprime la mailbox spécifiée de l'ensemble des mailboxes auxquelles vous avez "souscrit" |
.user : Text le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie |
IMAP New transporter
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
IMAP New transporter( server : Object ) : 4D.IMAPTransporter
Paramètres | Type | Description | |
---|---|---|---|
server | Object | -> | Informations sur le serveur IMAP |
Résultat | 4D.IMAPTransporter | <- | objet IMAP transporter |
|
Description
La commande IMAP New transporter
configure une nouvelle connexion IMAP selon le paramètre server et renvoie un nouvel objet transporter. L'objet transporteur retourné sera alors utilisé pour la réception d'emails.
Dans le paramètre server, passez un objet contenant les propriétés suivantes :
server | Valeur par défaut (si omise) |
---|---|
.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée | False |
.accessTokenOAuth2 : Text .accessTokenOAuth2 : Object Chaîne ou objet token représentant les informations d'autorisation OAuth2. Utilisé uniquement avec OAUTH2 authenticationMode . Si accessTokenOAuth2 est utilisé mais que authenticationMode est omis, le protocole OAuth 2 est utilisé (si le serveur l'autorise). Non retourné en objet IMAP transporter. | aucun |
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie | le mode d'authentification le plus sûr pris en charge par le serveur est utilisé |
.checkConnectionDelay : Integer la durée maximale (en secondes) autorisée avant vérification de la connexion au serveur | 300 |
.connectionTimeOut : Integer le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur | 30 |
.host : Text le nom ou l'adresse IP du serveur hôte | obligatoire |
.logFile : Text le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion | aucun |
.password : Text Mot de passe utilisateur pour l'authentification sur le serveur. Non retourné en objet IMAP transporter. | aucun |
.port : Integer le numéro de port utilisé pour les transactions d'emails | 993 |
.user : Text le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie | aucun |
Attention : Assurez-vous que le timeout défini est inférieur au timeout du serveur, sinon le timeout du client sera inutile.
Résultat
La fonction retourne un objet IMAP transporter. Toutes les propriétés retournées sont en lecture seule.
La connexion IMAP est automatiquement fermée lorsque l'objet transporteur est détruit.
Exemple
$server:=New object
$server.host:="imap.gmail.com" //Obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$server.logFile:="LogTest.txt" //log à sauvegarder dans le dossier Logs
var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)
$status:=$transporter.checkConnection()
If(Not($status.success))
ALERT("An error occurred: "+$status.statusText)
End if
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 IMAP transporter |
|
Description
La fonction 4D.IMAPTransporter.new()
crée et renvoie un nouvel objet du 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 |
---|---|
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
vous permet de passer un objet avec des valeurs de mots-clés pour les flags spécifiques à ajouter à msgIDs
. Vous pouvez utiliser les mots-clés suivants :
Paramètres | 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 |
- Les valeurs à faux sont ignorées.
- 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 objet 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 à l'aide des informations stockées dans l'objet transporteurrecrée la connexion si nécessaire, et renvoie son 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 maximal (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 dans 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 mailbox 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
.delete()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.delete( msgsIDs : Collection ) : Object
.delete( allMsgs : Integer ) : 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 |
Résultat | Object | <- | Statut de l'opération de suppression |
|
Description
La fonction delete()
associe le marqueur "deleted" aux messages désignés par msgsIDs
ou allMsgs
.
Vous pouvez passer :
- dans le paramètre
msgsIDs
, une collection contenant les ID uniques des messages spécifiques à supprimer, ou - dans le paramètre
allMsgs
, la constanteIMAP all
(integer) pour supprimer tous les messages de la boîte de réception sélectionnée.
L'exécution de cette fonction ne supprime pas réellement les messages. Les messages ayant le marqueur "deleted" peuvent toujours être trouvés par la fonction .searchMails(). Les messages marqués sont supprimés du serveur IMAP uniquement avec .expunge()
ou en sélectionnant une autre boîte de réception ou lorsque l'objet transporter (créé avec IMAP New transporter) est détruit.
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 supprimer 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 d'IDs unique des messages
$mailIds:=$transporter.searchMails("subject \"Reports\"")
// Supprimer les messages sélectionnés
$status:=$transporter.delete($mailIds)
Exemple 2
Pour supprimer 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)
//selection de la boîte
$boxInfo:=$transporter.selectBox("Junk Email")
// suppression de tous les messages de la boîte courante
$status:=$transporter.delete(IMAP all)
.deleteBox()
Historique
Release | Modifications |
---|---|
19 | Ajout |
.deleteBox( name : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la boîte de réception à supprimer |
Résultat | Object | <- | Statut de l'opération de suppression de boîte |
|
Description
La fonction .deleteBox()
supprime définitivement la boîte de réception nommée name
sur le serveur IMAP. Si vous tentez de supprimer la boîte INBOX ou une boîte de réception qui n'existe pas, une erreur sera générée.
Dans le paramètre name
, passez le nom de la mailbox à supprimer.
- La fonction ne peut pas supprimer une boîte de réception contenant des boîtes "enfant" si la boîte "parente" dispose de l'attribute "\Noselect".
- Tous les messages présents dans la boîte seront également supprimés.
- La possibilité de supprimer une boîte de réception dépend du serveur 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
Vous souhaitez supprimer la boîte enfant "Nova Orion Industries" à l'intérieur de la boîte "Bills" :
var $pw; $name : 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)
// delete mailbox
$name:="Bills"+$transporter.getDelimiter()+"Nova Orion Industries"
$status:=$transporter.deleteBox($name)
If ($status.success)
ALERT("Mailbox deletion successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
.expunge()
Historique
Release | Modifications |
---|---|
18 R6 | Ajout |
.expunge() : Object
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Object | <- | Statut de l'opération d'expunge |
|
Description
La fonction .expunge()
supprime tous les messages marqués "deleted" du serveur de messagerie IMAP. Le marqueur "deleted" peut être fixé avec les fonctions .delete()
ou .addFlags()
.
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
var $ids : Collection
$options:=New object
$options.host:="imap.gmail.com"
$options.port:=993
$options.user:="4d@gmail.com"
$options.password:="xxxxx"
// Creation du transporter
$transporter:=IMAP New transporter($options)
// Sélection de la boîte
$boxInfo:=$transporter.selectBox("INBOX")
// Chercher et sélectionner les messages lus dans INBOX
$ids:=$transporter.searchMails("SEEN")
$status:=$transporter.delete($ids)
// Purger tous les messages marqués deleted
$status:=$transporter.expunge()
.getBoxInfo()
Historique
Release | Modifications |
---|---|
18 R5 | name est optionnel |
|18 R4|Added|
.getBoxInfo( { name : Text }) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la boîte de réception |
Résultat | Object | <- | Objet boxInfo |
|
Description
La fonction .getBoxInfo()
renvoie un objet boxInfo
correspondant à la maibox courante ou à la mailbox nommée name. Cette fonction retourne les mêmes informations que .selectBox()
mais sans modifier la boite de réception courante.
Dans le paramètre name passez le nom de la mailbox à laquelle vous souhaitez accéder. Le nom doit représenter une hiérarchie claire, de gauche à droite, avec des niveaux séparés par un caractère délimiteur spécifique. Le délimiteur peut être récupéré à l'aide de la fonction .getDelimiter()
.
Si la boîte de réception nommée name n'est pas sélectionnable ou n'existe pas, la fonction génère une erreur et retourne null.
Objet retourné
L'objet boxInfo
contient les propriété suivantes :
Propriété | Type | Description |
---|---|---|
name | text | Nom de la boîte de réception |
mailCount | number | Nombre de messages contenus dans la boîte de réception |
mailRecent | number | Nombre de messages portant le marqueur "récent" (indiquant les nouveaux messages) |
Exemple
var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)
$info:=$transporter.getBoxInfo("INBOX")
ALERT("INBOX contains "+String($info.mailRecent)+" recent emails.")
.getBoxList()
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
19 | Ajout paramètre isSubscribed |
.getBoxList( { parameters : Object } ) : Collection
Paramètres | Type | Description | |
---|---|---|---|
parameters | Object | -> | Objet de paramètre |
Résultat | Collection | <- | Collection d'objets mailbox |
|
Description
La fonction .getBoxList()
renvoie une collection de boîtes aux lettres décrivant toutes les boîtes aux lettres disponibles. Cette fonction vous permet de gérer localement les listes de messages situés sur le serveur de messagerie IMAP.
Dans le paramètre optionnel parameters
, passez un objet contenant des valeurs de filtrage des boîtes de réception retournées. Vous pouvez passer :
Propriété | Type | Description |
---|---|---|
isSubscribed | Boolean |
Résultat
Chaque objet de la collection retournée contient les propriétés suivantes :
Propriété | Type | Description |
---|---|---|
[].name | text | Nom de la boîte de réception |
[].selectable | boolean | Indique si les droits d'accès permettent ou non à la boite de réception d'être sélectionnée :
|
[].inferior | boolean | Indique si les droits d'accès permettent ou non la création d'une hiérarchie inférieure dans la boite de réception :
|
[].interesting | boolean | Indique si la boite de réception a été marquée comme "intéressante" par le serveur :
|
Si le compte ne contient pas de boites de réception, une collection vide est retournée.
- Si aucune connexion n'est ouverte,
.getBoxList()
ouvrira une connexion.- Si la connexion n'a pas été utilisée depuis le délai de connexion (voir
IMAP New transporter
), la fonction.checkConnection( )
est automatiquement appelée.
Exemple
var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)
$boxList:=$transporter.getBoxList()
For each($box;$boxList)
If($box.interesting)
$split:=Split string($box.name;$transporter.getDelimiter())
ALERT("New emails are available in the box: "+$split[$split.length-1])
End if
End for each
.getDelimiter()
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.getDelimiter() : Text
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Text | <- | Caractère de délimitation de hiérarchie |
|
Description
La fonction .getDelimiter()
renvoie le caractère utilisé pour délimiter les niveaux de hiérarchie dans le nom de la boîte aux lettres.
Le délimiteur est un caractère pouvant être utilisé pour :
- créer des boites de réception de niveau inférieur
- rechercher des niveaux inférieurs ou supérieurs dans la hiérarchie de la boite de réception
Résultat
Caractère de délimitation des noms de boites de réception.
- Si aucune connexion n'est ouverte,
.getDelimiter()
ouvrira une connexion.- Si la connexion n'a pas été utilisée depuis le délai de connexion, la fonction
Exemple
var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)
$boxList:=$transporter.getBoxList()
For each($box;$boxList)
If($box.interesting)
$split:=Split string($box.name;$transporter.getDelimiter())
ALERT("New emails are available in the box: "+$split[$split.length-1])
End if
End for each
.getMail()
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.getMail( msgNumber: Integer { ; options : Object } ) : Object
.getMail( msgID: Text { ; options : Object } ) : Object
Paramètres | Type | Description | |
---|---|---|---|
msgNumber | Integer | -> | Numéro de séquence du message |
msgID | Text | -> | ID unique du message |
options | Object | -> | Instructions sur la gestion du message |
Résultat | Object | <- | Objet email |
|
Description
La fonction .getMail()
renvoie l'objet Email
correspondant au msgNumber ou msgID dans la boîte aux lettres désignée par IMAP_transporter
. Cette fonction vous permet de gérer localement le contenu de l'email.
Dans le premier paramètre, vous pouvez passer soit :
- msgNumber, une valeur integer indiquant le numéro de séquence du message à récupérer ou
- msgID, une valeur text indiquant l'ID unique du message à récupérer.
Le paramètre facultatif options vous permet de passer un objet définissant des instructions supplémentaires pour la gestion de votre message. Les propriétés suivantes sont disponibles :
Propriété | Type | Description |
---|---|---|
updateSeen | boolean | Si Vrai, le message est marqué comme "seen" (lu) dans la boite de réception. Si Faux, le message n'est pas marqué comme "seen". Valeur par défaut : Vrai |
withBody | boolean | Passez Vrai pour retourner le corps du message. Si Faux, seul l'en-tête du message est retourné. Valeur par défaut : Vrai |
- La fonction génère une erreur et retourne Null si msgID désigne un message non existant,
- Si aucune boite de réception n'est sélectionnée avec la fonction
.selectBox()
, une erreur est générée,- Si aucune connexion n'est ouverte,
.getMail()
ouvrira une connexion avec la dernière boite de réception spécifiée par.selectBox()
.
Résultat
.getMail()
retourne un objet Email
avec les propriétés IMAP supplémentaires suivantes : id, receivedAt et size.
Exemple
Vous souhaitez lire le message avec ID = 1 :
var $server : Object
var $info; $mail; $boxInfo : Variant
var $transporter : 4D.IMAPTransporter
$server:=New object
$server.host:="imap.gmail.com" //obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
//creation du transporter
$transporter:=IMAP New transporter($server)
//selection de la mailbox
$boxInfo:=$transporter.selectBox("Inbox")
//récupération de l'objet Email d'ID 1
$mail:=$transporter.getMail(1)
.getMails()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.getMails( ids : Collection { ; options : Object } ) : Object
.getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object
Paramètres | Type | Description | |
---|---|---|---|
ids | Collection | -> | Collection d'identifiants de messages |
startMsg | Integer | -> | Numéro de séquence du premier message |
endMsg | Integer | -> | Numéro de séquence du dernier message |
options | Object | -> | Instructions sur la gestion du message |
Résultat | Object | <- | Objet contenant :
|
|
Description
La fonction .getMails()
renvoie un objet contenant une collection d'objets Email
.
Première syntaxe :
.getMails( ids { ; options } ) -> result
La première syntaxe vous permet de récupérer des messages en fonction de leurs identifiants.
Dans le paramètre ids, passez une collection d'identifiants des messages à retourner. Vous pouvez obtenir les ID à l'aide de .getMail()
.
Le paramètre optionnel options vous permet de définir les parties de messages à retourner. Pour une description détaillée des propriétés disponibles, reportez-vous au tableau Options ci-dessous.
Deuxième syntaxe :
.getMails( startMsg ; endMsg { ; options } ) -> result
La deuxième syntaxe vous permet de récupérer des messages en fonction d'une plage séquentielle. Les valeurs passées représentent la position des messages dans la boite de réception.
Dans le paramètre startMsg, passez une valeur integer correspondant au numéro du premier message dans la plage séquentielle. Si vous passez un nombre négatif (startMsg <= 0), le premier message de la boîte de réception sera utilisé comme début de la séquence.
Dans le paramètre endMsg, passez une valeur integer correspondant au numéro du dernier message dans la plage séquentielle. Si vous passez un nombre négatif (endMsg <= 0), le dernier message de la boîte de réception sera utilisé comme fin de séquence.
Le paramètre optionnel options vous permet de définir les parties de messages à retourner.
Options
Propriété | Type | Description |
---|---|---|
updateSeen | Boolean | Si Vrai, les messages sont marqués comme "seen" (lus) dans la boite de réception. Si Faux, les messages ne sont pas marqués comme "seen". Valeur par défaut : Vrai |
withBody | Boolean | Passez Vrai pour retourner le corps des messages spécifiés. Si Faux, seuls les en-tête des messages sont retournés. Valeur par défaut : Vrai |
- Si aucune boite de réception n'est sélectionnée avec la fonction
.selectBox()
, une erreur est générée.- S'il n'y a pas de connexion ouverte,
.getMails()
ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de.selectBox()
.
Résultat
.getMails()
retourne un objet contenant les collections suivantes :
Propriété | Type | Description |
---|---|---|
liste | Collection | Collection d'objets Email . Si aucun objet Email n'est trouvé, une collection vide est retournée. |
notFound | Collection | Collection de :
|
Exemple
Vous souhaitez récupérer les 20 emails les plus récents sans modifier le statut "seen" :
var $server,$boxInfo,$result : Object
var $transporter : 4D.IMAPTransporter
$server:=New object
$server.host:="imap.gmail.com" //Mandatory
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
//create transporter
$transporter:=IMAP New transporter($server)
//select mailbox
$boxInfo:=$transporter.selectBox("INBOX")
If($boxInfo.mailCount>0)
// retrieve the headers of the last 20 messages without marking them as read
$result:=$transporter.getMails($boxInfo.mailCount-20;$boxInfo.mailCount;\
New object("withBody";False;"updateSeen";False))
For each($mail;$result.list)
// ...
End for each
End if
.getMIMEAsBlob()
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob
.getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob
Paramètres | Type | Description | |
---|---|---|---|
msgNumber | Integer | -> | Numéro de séquence du message |
msgID | Text | -> | ID unique du message |
updateSeen | Boolean | -> | Si Vrai, le message est marqué comme "seen" (lu) dans la boite de réception. Si Faux, le message demeure inchangé. |
Résultat | BLOB | <- | Blob de la chaine MIME retournée par le serveur mail |
|
Description
La fonction .getMIMEAsBlob()
copie les messages définis par msgsIDs ou allMsgs dans la destinationBox sur le serveur IMAP.
Dans le premier paramètre, vous pouvez passer soit :
- msgNumber, une valeur integer indiquant le numéro de séquence du message à récupérer ou
- msgID, une valeur text indiquant l'ID unique du message à récupérer.
Le paramètre optionnel updateSeen vous permet d'indiquer si le message est marqué comme "seen" (lu) dans la boîte de réception. Vous pouvez passer :
- Vrai - pour marquer le message comme "seen" (indiquant que le message a été lu)
- Faux - pour ne pas modifier le statut "seen" du message
- La fonction retourne un BLOB vide si msgNumber ou msgID désigne un message inexistant,
- 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) // rename mailbox $status:=$transporter.renameBox("Invoices"; "Bills") If ($status.success) ALERT("Mailbox renaming successful!") Else ALERT("Error: "+$status.statusText) End if End if Else ALERT("Error: "+$status.statusText) End if End if
- var $pw; $name : 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) $name:="Bills"+$transporter.getDelimiter()+"Atlas Corp" $status:=$transporter.unsubscribe($name) If ($status.success) ALERT("Mailbox unsubscription successful!") Else ALERT("Error: "+$status.statusText) End if End if Else ALERT("Error: "+$status.statusText) End if End if
Résultat
.getMIMEAsBlob()
retourne un BLOB
qui peut être archivé dans une base de données ou converti en un objet Email
avec la commande MAIL Convert from MIME
.
Exemple
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 d'IDs uniques des messages
$mailIds:=$transporter.searchMails("subject \"4D new feature:\"")
// déplacer les messages de la boite de réception courante vers la boite de réception "documents"
$status:=$transporter.move($mailIds;"documents")
.host
Historique
Release | Modifications |
---|---|
17 R5 | Ajout |
.host : Text
Description
La propriété .host
contient le nom ou l'adresse IP du serveur hôte. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).
.logFile
Historique
Release | Modifications |
---|---|
17 R5 | Ajout |
.logFile : Text
Description
La propriété .logFile
contient le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion. Le chemin peut être relatif (au dossier Logs courant) ou absolu.
Contrairement aux fichiers log habituels (activés via la commande SET DATABASE PARAMETER
), les fichiers log étendus stockent le contenu MIME de tous les emails envoyés et n'ont pas de limite de taille. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :
- Connexions SMTP - 4DSMTPLog.txt
- Connexions POP3 - 4DPOP3Log.txt
- Connexions IMAP - 4DIMAPLog.txt
.move()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.move( msgsIDs : Collection ; destinationBox : Text ) : Object
.move( 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 déplacés |
Résultat | Object | <- | Statut de l'opération de déplacement |
|
Description
La fonction .move()
déplace 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 à déplacer, ou
- dans le paramètre allMsgs, la constante
IMAP all
(integer) pour déplacer 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 déplacés.
Cette fonction est uniquement prise en charge par les serveurs IMAP compatibles avec RFC 8474.
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 déplacer une sélection de messages :
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")
// déplacer tous les messages de la boite de réception courante vers la boite de réception "documents"
$status:=$transporter.move(IMAP all;"documents")
Exemple 2
Pour déplacer tous les messages de la boîte de réception courante :
var $transporter : 4D.IMAPTransporter
var $server;$boxInfo;$status : Object
var $mailIds : Collection
$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 les IDs des 5 derniers messages reçus
$mailIds:=$transporter.numToID(($boxInfo.mailCount-5);$boxInfo.mailCount)
//supprimer les messages de la boite de réception courante
$status:=$transporter.delete($mailIds)
.numToID()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.numToID( startMsg : Integer ; endMsg : Integer ) : Collection
Paramètres | Type | Description | |
---|---|---|---|
startMsg | Integer | -> | Numéro de séquence du premier message |
endMsg | Integer | -> | Numéro de séquence du dernier message |
Résultat | Collection | <- | Collection d'identifiants uniques |
|
Description
La fonction .numToID()
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 dans la boîte de réception courante.
Dans le paramètre startMsg passez une valeur entier correspondant au numéro du premier message dans une plage séquentielle. Si vous passez un nombre négatif (startMsg <= 0), le premier message de la boîte de réception sera utilisé comme début de la séquence.
Dans le paramètre endMsg passez une valeur entier long correspondant au numéro du dernier message à inclure dans une plage séquentielle. Si vous passez un nombre négatif (endMsg <= 0), le dernier message de la boîte de réception sera utilisé comme fin de séquence.
Résultat
La fonction retourne une collection de chaînes (IDs uniques).
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 le transporteur
$transporter:=IMAP New transporter($options)
// Sélectionner la boite de réception
$boxInfo:=$transporter.selectBox("INBOX")
// Marquer tous les messages de la boite de réception comme étant non vus
$flags:=New object
$flags["$seen"]:=True
$status:=$transporter.removeFlags(IMAP all;$flags)
.removeFlags()
Historique
Release | Modifications |
---|---|
18 R6 | Ajout |
.removeFlags( msgIDs : Collection ; keywords : Object ) : Object
.removeFlags( msgIDs : Text ; keywords : Object ) : Object
.removeFlags( 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 à supprimer |
Résultat | Object | <- | Statut de l'opération removeFlags |
|
Description
La fonction .removeFlags()
supprime les flags des 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
vous permet de passer un objet avec des valeurs de mots-clés pour les flags spécifiques à supprimer des msgIDs
. Vous pouvez utiliser les mots-clés suivants :
Paramètres | Type | Description |
---|---|---|
$draft | Boolean | True pour supprimer le marqueur "draft" du message |
$seen | Boolean | True pour supprimer le marqueur "seen" du message |
$flagged | Boolean | True pour supprimer le marqueur "flagged" du message |
$answered | Boolean | True pour supprimer le marqueur "answered" du message |
$deleted | Boolean | True pour supprimer le marqueur "deleted" du message |
Les valeurs à faux sont ignorées.
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 $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)
// renommer la boite de réception
$status:=$transporter.renameBox("Invoices"; "Bills")
If ($status.success)
ALERT("Mailbox renaming successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
.renameBox()
Historique
Release | Modifications |
---|---|
19 | Ajout |
.renameBox( currentName : Text ; newName : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
currentName | Text | -> | Nom actuel de la boîte de réception |
nouveauNom | Text | -> | Nom de la nouvelle mailbox |
Résultat | Object | <- | Statut de l'opération de renommage |
|
Description
La fonction .renameBox()
change le nom d'une boîte aux lettres sur le serveur IMAP. Essayer de renommer une mailbox qui n'existe pas ou de renommer une mailbox avec un nom qui est déjà utilisé génère une erreur.
Dans le paramètre currentName
, passez le nom de la mailbox à renommer.
Passez le nouveau nom de la mailbox dans e paramètre newName
.
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 renommer la mailbox “Invoices” en “Bills”:
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)
// rename mailbox
$status:=$transporter.renameBox("Invoices"; "Bills")
If ($status.success)
ALERT("Mailbox renaming successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
Else
ALERT("Error: "+$status.statusText)
End if
End if
.port
Historique
Release | Modifications |
---|---|
17 R4 | Ajout |
.port : Integer
Description
La propriété .port
contient le numéro de port utilisé pour les transactions d'emails. Par défaut, si la propriété port 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
), le port utilisé est :
- SMTP - 587
- POP3 - 995
- IMAP - 993
.searchMails()
Historique
Release | Modifications |
---|---|
18 R5 | Ajout |
.searchMails( searchCriteria : Text ) : Collection
Paramètres | Type | Description | |
---|---|---|---|
searchCriteria | Text | -> | Critère(s) de recherche |
Résultat | Collection | <- | Collection de numéros de messages |
|
Description
Cette fonction est basée sur la spécification du protocole IMAP.
La fonction .searchMails()
recherche les messages qui correspondent aux critères de recherche searchCriteria dans la boîte de réception courante. .
searchCriteria est un paramètre texte listant un ou plusieurs critères de recherche (voir Mots-clés de recherche autorisés ci-dessous) associés ou non à des valeurs à rechercher. Un critère de recherche peut être composé d'un ou plusieurs éléments. Par exemple :
SearchKey1 = FLAGGED
SearchKey2 = NOT FLAGGED
SearchKey3 = FLAGGED DRAFT
La correspondance n'est généralement pas sensible à la casse
- Si searchCriteria est une chaîne vide, la recherche sera équivalente à un "tout sélectionner".
- Si searchCriteria contient plusieurs mots-clés de recherche, le résultat est l'intersection (fonction ET) de tous les messages qui correspondent à ces critères.
searchCriteria = FLAGGED FROM "SMITH"
... retourne tous les messages comportant le marqueur \Flagged ET envoyés par Smith.
- Vous pouvez utiliser les opérateurs OR ou NOT comme suit :
searchCriteria = OR SEEN FLAGGED
... retourne tous les messages comportant le marqueur \Seen OU \Flagged
searchCriteria = NOT SEEN
... retourne tous les messages ne comportant pas le marqueur \Seen.
searchCriteria = HEADER CONTENT-TYPE "MIXED" NOT HEADER CONTENT-TYPE "TEXT"...
... retourne les messages dont l'en-tête content-type contient “Mixed” et ne contient pas “Text”.
searchCriteria = HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED"
... retourne les messages dont l'en-tête content-type contient “ e ” et dont l'en-tête Subject ne contient pas “ o ” et dont l'en-tête content-type n'est pas “ Mixed ”.
A noter que dans les deux derniers exemples, le résultat de la recherche est différent lorsque vous enlevez les parenthèses de la première liste de mots-clés.
- Le paramètre searchCriteria peut inclure optionnellement l'instruction [CHARSET]. Cette instruction est composée du mot "CHARSET" suivi d'un jeu de caractères défini [CHARSET] (US ASCII, ISO-8859). Elle indique le codage de caractères utilisé dans la chaine searchCriteria. Par conséquent, vous devez convertir la chaîne searchCriteria dans le jeu de caractères spécifié si vous utilisez l'instruction [CHARSET] (voir les commandes
CONVERT FROM TEXT
ouConvert to text
). Par défaut, 4D encode la chaîne de critères searchCriteria en "Quotable Printable" si elle contient des caractères étendus.
searchCriteria = CHARSET "ISO-8859" BODY "Help"
signifie que le critère de recherche utilise le jeu de caractères iso-8859 et que le serveur devra convertir la chaîne avant la recherche, si nécessaire.
Mots-clés de recherche autorisés
Les mots-clés de recherche peuvent traiter des valeurs des types suivants :
-
Valeurs de type date : Les valeurs de type date sont placées dans des chaînes formatées de la manière suivante : date-day+"-"+date-month+"-"+date-year où date-day indique la date du jour dans le mois (2 caractères maxi), date-month indique le mois (Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Dec) et date-year indique l’année sur 4 chiffres. Exemple :
searchCriteria = SENTBEFORE 1-Feb-2020
(il n’est généralement pas nécessaire de mettre une date entre guillemets puisqu’elle ne contient pas de caractères spéciaux) -
**Valeurs de type chaîne ** : Les valeurs de type chaîne peuvent contenir tout type de caractère et doivent être placées entre des guillemets. Toutefois, si la chaîne ne contient pas de caractères spéciaux (des espaces par exemple), les guillemets ne sont pas obligatoires. Dans tous les cas, les guillemets vous permettent de vous assurer que la chaîne sera correctement interprétée. Example:
searchCriteria = FROM "SMITH"
For all search keys that use strings, a message matches the key if the string is a substring of the field. La recherche ne tient pas compte de la casse des caractères. -
Noms de champs : Les valeurs de type nom de champ contiennent le nom d’un champ d’en-tête. Exemple :
searchCriteria = HEADER CONTENT-TYPE "MIXED"
-
Marqueurs : Les valeurs de type marqueur (flags) acceptent un ou plusieurs mots-clés (y compris des marqueurs standard) séparés par des espaces. Exemple :
searchCriteria = KEYWORD \Flagged \Draft
-
Ensemble de messages : Les valeurs de ce type désignent un ensemble de messages. Elles contiennent une liste de numéros de messages dans un ordre croissant, de 1 au nombre total de messages dans la boîte aux lettres. Les numéros sont séparés par des virgules ; un deux-points (:) indique un intervalle (inclusif) de numéros. Examples:
2,4:7,9,12:*
is2,4,5,6,7,9,12,13,14,15
for a mailbox with 15 messages.searchCriteria = 1:5 ANSWERED
recherche, parmi les messages 1 à 5, ceux qui comportent le marqueur \Answered.searchCriteria= 2,4 ANSWERED
recherche, parmi les messages 2 et 4, ceux qui comportent le marqueur \Answered.
Mots-clés de recherche autorisés
ALL: Tous les messages de la boîte de réception.
ANSWERED: Messages comportant le marqueur \Answered.
UNANSWERED: Messages ne comportant pas le marqueur \Answered.
DELETED: Messages comportant le marqueur \Deleted.
UNDELETED: Messages ne comportant pas le marqueur \Deleted.
DRAFT: Messages comportant le marqueur \Draft.
UNDRAFT: Messages ne comportant pas le marqueur \Draft.
FLAGGED: Messages comportant le marqueur \Flagged.
UNFLAGGED: Messages ne comportant pas le marqueur \Flagged.
RECENT: Messages comportant le marqueur \Recent.
OLD: Messages ne comportant pas le marqueur \Recent.
SEEN: Messages comportant le marqueur \Seen.
UNSEEN: Messages ne comportant pas le marqueur \Seen.
NEW: Messages comportant le marqueur \Recent et pas le marqueur \Seen. Equivaut à “(RECENT UNSEEN)”.
KEYWORD flag : Messages comportant le marqueur spécifié.
UNKEYWORD flag: Messages ne comportant pas le marqueur spécifié.
BEFORE date: Messages dont la date interne est antérieure à la date spécifiée.
ON date: Messages dont la date interne est égale à la date spécifiée.
SINCE date: Messages dont la date interne est égale ou postérieure à la date spécifiée.
SENTBEFORE date: Messages dont l’en-tête Date est antérieur à la date spécifiée.
SENTON date: Messages dont l’en-tête Date est égal à la date spécifiée.
SENTSINCE date: Messages dont l’en-tête Date est égal ou postérieur à la date spécifiée.
TO string: Messages contenant la chaîne spécifiée dans l’en-tête Destinataire.
FROM string: Messages contenant la chaîne spécifiée dans l’en-tête Emetteur.
CC string: Messages contenant la chaîne spécifiée dans l’en-tête CC.
BCC string: Messages contenant la chaîne spécifiée dans l’en-tête BCC.
SUBJECT string: Messages contenant la chaîne spécifiée dans l’en-tête Objet.
BODY string: Messages dont le corps contient la chaîne spécifiée.
TEXT string: Messages contenant la chaîne spécifiée dans l’en-tête ou le corps.
HEADER field-name string: Messages dont l’en-tête contient le champ défini et dont ce champ contient la chaîne définie.
UID message-UID: Messages dont le numéro unique correspond à la valeur spécifiée.
LARGER n: Messages dont la taille en octets est supérieure à la taille spécifiée.
SMALLER n: Messages dont la taille en octets est inférieure à la taille spécifiée.
NOT search-key: Messages ne correspondant pas au critère spécifié.
OR search-key1 search-key2: Messages correspondant au premier ou au deuxième critère spécifié.
.selectBox()
Historique
Release | Modifications |
---|---|
18 R4 | Ajout |
.selectBox( name : Text { ; state : Integer } ) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la boîte de réception |
state | Integer | -> | Statut de l'accès à la boite de réception |
Résultat | Object | <- | Objet boxInfo |
|
Description
La fonction .selectBox()
sélectionne la mailbox name comme boîte aux lettres courante. Cette fonction vous permet de récupérer des informations sur la boite de réception.
Pour lire les informations à partir d'une mailbox sans changer la mailbox courante, utilisez
.getBoxInfo()
.
Dans le paramètre optionnel name passez le nom de la boite de réception à laquelle vous souhaitez accéder. Le nom doit représenter une hiérarchie claire, de gauche à droite, avec des niveaux séparés par un caractère délimiteur spécifique. Le délimiteur peut être récupéré à l'aide de la fonction .getDelimiter()
.
Le paramètre optionnel state définit le type d'accès à la mailbox. Les valeurs possibles sont les suivantes :
Constante | Valeur | Commentaire |
---|---|---|
IMAP read only state | 1 | La mailbox sélectionnée est accessible avec les privilèges de lecture seule. Les messages contenant un marqueur "recent" (indication de nouveaux messages) restent inchangés. |
IMAP read write state | 0 | La mailbox sélectionnée est accessible avec des privilèges de lecture et d'écriture. Les messages sont considérés "seen" et perdent le marqueur "recent" (indication des nouveaux messages). (Valeur par défaut) |
- La fonction génère une erreur et retourne Null si name désigne une mailbox inexistante.
- Si aucune connexion n'est ouverte,
.selectBox()
ouvrira une connexion.- Si la connexion n'a pas été utilisée depuis le délai de connexion (voir
IMAP New transporter
), la fonction.checkConnection( )
est automatiquement appelée.
Objet retourné
L'objet boxInfo
contient les propriété suivantes :
Propriété | Type | Description |
---|---|---|
name | Text | Nom de la boîte de réception |
mailCount | number | Nombre de messages contenus dans la boîte de réception |
mailRecent | number | Nombre de messages avec le marqueur "recent" |
Exemple
var $pw; $name : 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)
$name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
$status:=$transporter.subscribe($name)
If ($status.success)
ALERT("Mailbox subscription successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
Else
ALERT("Error: "+$status.statusText)
End if
End if
.subscribe()
Historique
Release | Modifications |
---|---|
19 | Ajout |
.subscribe( name : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la boîte de réception |
Résultat | Object | <- | Statut de l'opération subscribe |
|
Description
La fonction .subscribe()
permet d'ajouter la boîte aux lettres spécifiée à l'ensemble des mailboxes auxquelles vous avez "souscrit" sur le serveur IMAP. Ainsi, vous pouvez contrôler la taille de la liste des boîtes de réception disponibles en souscrivant uniquement à celles que vous souhaitez généralement consulter.
Dans le paramètre name
, passez le nom de la mailbox à ajouter (subscribe) à la liste de mailboxes auxquelles vous avez "souscrit".
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 souscrire à la mailbox "Atlas Corp” dans la hiérarchie "Bills" :
var $pw; $name : 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)
$name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
$status:=$transporter.subscribe($name)
If ($status.success)
ALERT("Mailbox subscription successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
Else
ALERT("Error: "+$status.statusText)
End if
End if
Else
ALERT("Error: "+$status.statusText)
End if
End if
.unsubscribe()
Historique
Release | Modifications |
---|---|
19 | Ajout |
.unsubscribe( name : Text ) : Object
Paramètres | Type | Description | |
---|---|---|---|
name | Text | -> | Nom de la boîte de réception |
Résultat | Object | <- | Statut de l'opération unsubscribe |
|
Description
La fonction .unsubscribe()
supprime la mailbox spécifiée de l'ensemble des mailboxes auxquelles vous avez "souscrit". Elle vous permet de réduire le nombre de mailboxes que vous consultez régulièrement.
Dans le paramètre name
, passez le nom de la mailbox à supprimer (unsubscribe) de la liste de mailboxes auxquelles vous avez "souscrit".
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 ne plus souscrire à la mailbox "Atlas Corp” dans la hiérarchie "Bills" :
var $pw; $name : 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)
$name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
$status:=$transporter.unsubscribe($name)
If ($status.success)
ALERT("Mailbox unsubscription successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
Else
ALERT("Error: "+$status.statusText)
End if
End if
.user
Historique
Release | Modifications |
---|---|
17 R4 | Ajout |
.user : Text
Description
La propriété .user
contient le nom d'utilisateur employé pour l'authentification sur le serveur de messagerie.