Version: 20

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
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 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	headerCharset : US-ASCII si possible, japonais (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset : US-ASCII si possible, japonais (ISO-2022-JP) et 7 bits si possible, sinon UTF-8 et Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
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 constante IMAP 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
20	id est renvoyé
18 R5	name est optionnel
18 R4	Ajout

.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)
id	text	Identifiant unique de la boîte aux lettres

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	True pour retourner uniquement les boîtes auxquelles vous êtes abonné False pour retourner toutes les boîtes de réception disponibles

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 : vrai - la boite de réception peut être sélectionnée faux - la boite de réception ne peut pas ê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 : vrai - un niveau inférieur peut être créé faux - un niveau inférieur ne peut pas être créé
[].interesting	boolean	Indique si la boite de réception a été marquée comme "intéressante" par le serveur : vrai - la boite de réception a été marquée comme "intéressante" par le serveur. Par exemple, elle peut contenir de nouveaux messages. faux - la boite de réception n'a pas é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 : une collection d'objets Email et une collection d'identifiants ou de numéros des messages manquants, le cas échéant

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 : première syntaxe - IDs de messages passés antérieurement qui n'existent pas deuxième syntaxe - numéros de séquence des messages entre startMsg et endMsg qui n'existent pas Une collection vide est retournée si tous les messages sont trouvés.

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
20	Prise en charge des mots-clés personnalisés (custom keywords)
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 définir les flags à supprimer des msgIDs. Vous pouvez utiliser les flags standard suivants ainsi que des flags personnalisés :

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
`<custom flag>`	Boolean	True pour supprimer le flag personnalisé du message

Reportez-vous à .addFlags() pour plus d'informations sur les flags personnalisés.

Pour qu'un mot-clé soit pris en compte, il doit être à vrai.

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 ou Convert 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:* is 2,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
20	id, flags, permanentFlags sont renvoyés
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"
id	text	Identifiant unique de la boîte aux lettres
flags	text	Liste des flags actuellement utilisés pour la boîte aux lettres, séparés par des espaces
permanentFlags	text	Liste des flags que le client peut modifier en permanence (à l'exception de l'indicateur \Recent, qui est géré par le serveur IMAP), séparés par des espaces

info

Si la chaîne permanentFlags comprend le flag spécial *, cela signifie que le serveur prend en charge les flags personnalisés.

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

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.

Objet IMAP Transporter​

IMAP New transporter​

Description​

Résultat​

Exemple​

4D.IMAPTransporter.new()​

Description​

.acceptUnsecureConnection​

Description​

.addFlags()​

Description​

Exemple​

.append()​

Description​

Exemple​

.authenticationMode​

Description​

.checkConnection()​

Description​

Objet retourné​

.checkConnectionDelay​

Description​

.connectionTimeOut​

Description​

.copy()​

Description​

Exemple 1​

Exemple 2​

.createBox()​

Description​

Exemple​

.delete()​

Description​

Exemple 1​

Exemple 2​

.deleteBox()​

Description​

Exemple​

.expunge()​

Description​

Exemple​

.getBoxInfo()​

Description​

Exemple​

.getBoxList()​

Description​

Résultat​

Exemple​

.getDelimiter()​

Description​

Résultat​

Exemple​

.getMail()​

Description​

Résultat​

Exemple​

.getMails()​

Description​

Résultat​

Exemple​

.getMIMEAsBlob()​

Description​

Résultat​

Exemple​

.host​

Description​

.logFile​

Description​

.move()​

Description​

Exemple 1​

Exemple 2​

.numToID()​

Description​

Résultat​

Exemple​

.removeFlags()​

Description​

Exemple​

.renameBox()​

Objet IMAP Transporter

IMAP New transporter

Description

Résultat

Exemple

4D.IMAPTransporter.new()

Description

.acceptUnsecureConnection

Description

.addFlags()

Description

Exemple

.append()

Description

Exemple

.authenticationMode

Description

.checkConnection()

Description

Objet retourné

.checkConnectionDelay

Description

.connectionTimeOut

Description

.copy()

Description

Exemple 1

Exemple 2

.createBox()

Description

Exemple

.delete()

Description

Exemple 1

Exemple 2

.deleteBox()

Description

Exemple

.expunge()

Description

Exemple

.getBoxInfo()

Description

Exemple

.getBoxList()

Description

Résultat

Exemple

.getDelimiter()

Description

Résultat

Exemple

.getMail()

Description

Résultat

Exemple

.getMails()

Description

Résultat

Exemple

.getMIMEAsBlob()

Description

Résultat

Exemple

.host

Description

.logFile

Description

.move()

Description

Exemple 1

Exemple 2

.numToID()

Description

Résultat

Exemple

.removeFlags()

Description

Exemple

.renameBox()