Version: 20 R7 BETA

IMAPTransporter

La classe IMAPTransporter vous permet de récupérer des messages à partir d'un serveur de messagerie IMAP.

Objet IMAP Transporter

Les objets IMAP Transporter sont instanciés avec la commande IMAP New transporter. Leurs propriétés et fonctions sont les suivantes :


.acceptUnsecureConnection : Boolean True si 4D est autorisé à établir une connexion non chiffrée
.addFlags( msgIDs : Collection ; keywords : Object ) : Object .addFlags( msgIDs : Text ; keywords : Object ) : Object .addFlags( msgIDs : Longint ; keywords : Object ) : Object ajoute des flags (drapeaux) aux `msgIDs` pour les `keywords` spécifiés
.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object ajoute un `mailObj` à la boîte `destinationBox`
.authenticationMode : Text le mode d'authentification utilisé pour ouvrir la session sur le serveur de messagerie
.checkConnection() : Object vérifie la connexion en utilisant les informations stockées dans l'objet transporteur
.checkConnectionDelay : Integer la durée maximale (en secondes) autorisée avant vérification de la connexion au serveur
.connectionTimeOut : Integer le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur
.copy( msgsIDs : Collection ; destinationBox : Text ) : Object .copy( allMsgs : Integer ; destinationBox : Text ) : Object copie les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP
.createBox( name : Text ) : Object crée une boîte de réception avec le `name` passé en paramètre
.delete( msgsIDs : Collection ) : Object .delete( allMsgs : Integer ) : Object associe le marqueur "deleted" aux messages définis dans `msgsIDs` ou `allMsgs`
.deleteBox( name : Text ) : Object supprime définitivement la boîte de réception nommée `name` sur le serveur IMAP
.expunge() : Object supprime tous les messages marqués "deleted" du serveur de messagerie IMAP.
.getBoxInfo( { name : Text }) : Object retourne un objet `boxInfo` correspondant à la boîte de réception courante ou à la boîte de réception nommée name
.getBoxList( { parameters : Object } ) : Collection retourne une collection de boîtes aux lettres décrivant toutes les boîtes aux lettres disponibles
.getDelimiter() : Text retourne le caractère utilisé pour délimiter les niveaux de hiérarchie dans le nom de la boîte aux lettres
.getMail( msgNumber: Integer { ; options : Object } ) : Object .getMail( msgID: Text { ; options : Object } ) : Object retourne l'objet `Email` correspondant au msgNumber ou msgID dans la boite de réception désignée par l'`IMAP_transporter`
.getMails( ids : Collection { ; options : Object } ) : Object .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object retourne un objet contenant une collection d'objets `Email`
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob retourne un BLOB avec le contenu MIME du message correspondant au msgNumber ou msgID dans la boîte de réception désignée par le `IMAP_transporter`
.host : Text le nom ou l'adresse IP du serveur hôte
.logFile : Text le chemin du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie
.move( msgsIDs : Collection ; destinationBox : Text ) : Object .move( allMsgs : Integer ; destinationBox : Text ) : Object déplace les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP
.numToID( startMsg : Integer ; endMsg : Integer ) : Collection convertit les numéros de séquence en identifiants uniques IMAP pour les messages de la plage séquentielle désignée par startMsg et endMsg
.removeFlags( msgIDs : Collection ; keywords : Object ) : Object .removeFlags( msgIDs : Text ; keywords : Object ) : Object .removeFlags( msgIDs : Longint ; keywords : Object ) : Object supprime les flags (drapeaux) des `msgIDs` pour les `keywords` spécifiés
.renameBox( currentName : Text ; newName : Text ) : Object change le nom d'une boîte de réception sur le serveur IMAP
.port : Integer le numéro de port utilisé pour les transactions de courrier
.searchMails( searchCriteria : Text ) : Collection recherche les messages qui correspondent aux critères de recherche searchCriteria dans la boîte aux lettres courante
.selectBox( name : Text { ; state : Integer } ) : Object sélectionne la boîte de réception name comme boîte de réception courante
.subscribe( name : Text ) : Object permet d'ajouter la boîte spécifiée à l'ensemble des boîtes auxquelles vous avez "souscrit" sur le serveur IMAP
.unsubscribe( name : Text ) : Object supprime la boîte spécifiée de l'ensemble des boîtes auxquelles vous avez "souscrit"
.user : Text le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie

4D.IMAPTransporter.new()

4D.IMAPTransporter.new( server : Object ) : 4D.IMAPTransporter

Paramètres	Type		Description
server	Object	->	Informations sur le serveur IMAP
Résultat	4D.IMAPTransporter	<-	Objet transporteur IMAP

Description

La fonction 4D.IMAPTransporter.new() crée et retourne un nouvel objet de type 4D.IMAPTransporter. Elle est identique à la commande IMAP New transporter (raccourci).

.acceptUnsecureConnection

Historique

Release	Modifications
17 R4	Ajout

.acceptUnsecureConnection : Boolean

Description

La propriété .acceptUnsecureConnection contient True si 4D est autorisé à établir une connexion non chiffrée lorsqu'une connexion chiffrée n'est pas possible.

Elle contient False si les connexions non chiffrées ne sont pas autorisées, auquel cas une erreur est retournée lorsque la connexion chiffrée n'est pas possible.

Ports sécurisés disponibles :

SMTP
- 465: SMTPS
- 587 ou 25 : SMTP avec mise à niveau STARTTLS si le serveur le prend en charge.
IMAP
- 143 : Port IMAP non chiffré
- 993 : IMAP avec mise à niveau STARTTLS si le serveur le prend en charge
POP3
- 110 : Port POP3 non chiffré
- 995 : POP3 avec mise à niveau STARTTLS si le serveur le prend en charge.

.addFlags()

Historique

Release	Modifications
20	Prise en charge des mots-clés personnalisés (custom keywords)
18 R6	Ajout

.addFlags( msgIDs : Collection ; keywords : Object ) : Object
.addFlags( msgIDs : Text ; keywords : Object ) : Object
.addFlags( msgIDs : Longint ; keywords : Object ) : Object

Paramètres	Type		Description
msgIDs	Collection	->	Collection de chaînes : IDs uniques des messages (texte) Texte : ID unique d'un message Numérique (IMAP all) : Tous les messages de la boîte sélectionnée
keywords	Object	->	Mots-clés de flags à ajouter
Résultat	Object	<-	Statut de l'opération addFlags

Description

La fonction .addFlags() ajoute des flags (drapeaux) aux msgIDs pour les keywords spécifiés.

Dans le paramètre msgIDs, vous pouvez passer soit :

une collection contenant les IDs uniques de messages spécifiques, ou
l'ID unique (texte) d'un seul message ou
la constante suivante (entier long) pour tous les messages de la boîte sélectionnée :

Constante	Valeur	Commentaire
IMAP all	1	Sélectionner tous les messages de la boîte sélectionnée

Le paramètre keywords permet de définir les flags à ajouter aux msgIDs. Vous pouvez utiliser les flags standard suivants ainsi que des flags personnalisés (la prise en charge des flags personnalisés dépend de l'implémentation du serveur) :

Propriété	Type	Description
$draft	Boolean	True pour ajouter le marqueur "draft" au message
$seen	Boolean	True pour ajouter le marqueur "seen" au message
$flagged	Boolean	True pour ajouter le marqueur "flagged" au message
$answered	Boolean	True pour ajouter le marqueur "answered" au message
$deleted	Boolean	True pour ajouter le marqueur "deleted" au message
`<custom flag>`	Boolean	True pour ajouter le flag personnalisé au message

Les noms des flags personnalisés doivent respecter cette règle : le mot-clé doit être une chaîne non sensible à la casse, excluant les caractères de contrôle et les espaces, et ne peut inclure aucun de ces caractères : ( ) { ] % * " \

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

L'interprétation des indicateurs de mots-clés peut varier selon le client de messagerie.

Objet retourné

La fonction retourne un objet décrivant le statut IMAP :

Propriété		Type	Description
success		Boolean	Vrai si l'opération est réussie, sinon Faux
statusText		Text	Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		Collection	Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
	[].errcode	Number	Code d'erreur 4D
	[].message	Text	Description de l'erreur 4D
	[].componentSignature	Text	Signature du composant interne qui a retourné l'erreur

Exemple

var $options;$transporter;$boxInfo;$status : Object

$options:=New object
$options.host:="imap.gmail.com"
$options.port:=993
$options.user:="4d@gmail.com"
$options.password:="xxxxx"

// Créer transporteur
$transporter:=IMAP New transporter($options)

// Sélectionner la boîte de messagerie
$boxInfo:=$transporter.selectBox("INBOX")

// Marquer tous les messages de la boite de réception (INBOX) comme étant lus/vus
$flags:=New object
$flags["$seen"]:=True
$status:=$transporter.addFlags(IMAP all;$flags)

.append()

Historique

Release	Modifications
18 R6	Ajout

.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object

Paramètres	Type		Description
mailObj	Object	->	Objet email
destinationBox	Text	->	Mailbox devant recevoir l'objet email
options	Object	->	Objet contenant les informations de charset
Résultat	Object	<-	Statut de l'opération

Description

La fonction .append() ajoute un mailObj à la boîte destinationBox.

Dans le paramètre mailObj, passez un objet email. Pour une description détaillée des propriétés de mail, reportez-vous à Objet Email. La fonction .append() prend en charge les marqueurs de mots-clés dans l'attribut keywords des objets email.

Le paramètre optionnel destinationBox vous permet de passer le nom de la boîte de réception dans laquelle l'objet mailObj sera ajouté. S'il est omis, la mailbox courante sera utilisée.

Dans le paramètre optionnel options, vous pouvez passer un objet permettant de définir le charset et l'encodage des différentes parties de l'email. Propriétés disponibles :

Propriété	Type	Description
headerCharset	Text	Charset et encodage utilisés pour les parties de mail suivantes : le sujet, les noms de fichiers joints et le nom du mail. Valeurs possibles : voir le tableau des charsets possibles
bodyCharset	Text	Charset et encodage utilisés pour le contenu html et le texte du body du mail. Valeurs possibles : voir le tableau des charsets possibles

Charsets possibles :

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset : US-ASCII si possible, Japanese (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable bodyCharset : US-ASCII si possible, Japanese (ISO-2022-JP) & 7-bit si possible, sinon UTF-8 & 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 en utilisant les informations stockées dans l'objet transporteur, recrée la connexion si nécessaire et renvoie le statut. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.

Objet retourné

La fonction envoie une requête au serveur de mail et retourne un objet décrivant le statut. Cet objet peut avoir les propriétés suivantes :

Propriété		Type	Description
success		boolean	Vrai si la vérification a été effectuée avec succès, sinon Faux
status		number	(SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail)
statusText		text	Message du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		collection	Pile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue)
	[ ].errCode	number	Code d'erreur 4D
	[ ].message	text	Description de l'erreur 4D
	[ ].componentSignature	text	Signature du composant interne qui a retourné l'erreur

.checkConnectionDelay

Historique

Release	Modifications
18 R4	Ajout

.checkConnectionDelay : Integer

Description

La propriété .checkConnectionDelay contient la durée maximale (en secondes) autorisée avant vérification de la connexion au serveur. Si cette durée est dépassée entre deux appels de méthodes, la connexion au serveur sera vérifiée. Par défaut, si la propriété n'a pas été définie dans l'objet server, la valeur est de 300.

Attention : Assurez-vous que le timeout défini est inférieur au timeout du serveur, sinon le timeout du client sera inutile.

.connectionTimeOut

Historique

Release	Modifications
17 R5	Ajout

.connectionTimeOut : Integer

Description

La propriété .connectionTimeOut contient le temps d'attente maximum (en secondes) autorisé pour établir une connexion avec le serveur. Par défaut, si la propriété n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), la valeur utilisée est 30.

.copy()

Historique

Release	Modifications
18 R5	Ajout

.copy( msgsIDs : Collection ; destinationBox : Text ) : Object
.copy( allMsgs : Integer ; destinationBox : Text ) : Object

Paramètres	Type		Description
msgsIDs	Collection	->	Collection d'IDs uniques de messages (texte)
allMsgs	Integer	->	`IMAP all` : tous les messages de la boîte de réception sélectionnée
destinationBox	Text	->	Boîte de réception recevant les messages copiés
Résultat	Object	<-	Statut de l'opération de copie

Description

La fonction .copy() copie les messages définis par msgsIDs ou allMsgs vers la destinationBox sur le serveur IMAP.

Vous pouvez passer :

dans le paramètre msgsIDs, une collection contenant les ID uniques des messages spécifiques à copier, ou
dans le paramètre allMsgs, la constante IMAP all (integer) pour copier tous les messages de la boîte de réception sélectionnée.

Le paramètre destinationBox vous permet de passer une valeur texte avec le nom de la boîte de réception dans laquelle seront placés les messages copiés.

Objet retourné

La fonction retourne un objet décrivant le statut IMAP :

Propriété		Type	Description
success		Boolean	Vrai si l'opération est réussie, sinon Faux
statusText		Text	Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		Collection	Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
	[].errcode	Number	Code d'erreur 4D
	[].message	Text	Description de l'erreur 4D
	[].componentSignature	Text	Signature du composant interne qui a retourné l'erreur

Exemple 1

Pour copier une sélection de messages :

 var $server;$boxInfo;$status : Object
 var $mailIds : Collection
 var $transporter : 4D.IMAPTransporter

 $server:=New object
 $server.host:="imap.gmail.com" //Obligatoire
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=IMAP New transporter($server)

  //sélectionner la boite de réception
 $boxInfo:=$transporter.selectBox("inbox")

  //obtenir la collection des IDs uniques de message
 $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")

  // copier les messages identifiés dans la boîte de réception "documents"
 $status:=$transporter.copy($mailIds;"documents")

Exemple 2

Pour copier tous les messages de la boîte de réception courante :

 var $server;$boxInfo;$status : Object
 var $transporter : 4D.IMAPTransporter

 $server:=New object
 $server.host:="imap.gmail.com" //Obligatoire
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=IMAP New transporter($server)

  //sélectionner la boite de réception

 $boxInfo:=$transporter.selectBox("inbox")

  // copier les messages dans la boîte de réception "documents"
 $status:=$transporter.copy(IMAP all;"documents")

.createBox()

Historique

Release	Modifications
19	Ajout

.createBox( name : Text ) : Object

Paramètres	Type		Description
name	Text	->	Nom de la nouvelle mailbox
Résultat	Object	<-	Statut de l'opération de création de mailbox

Description

La fonction .createBox() crée une boîte de réception avec le name passé en paramètre. Si le caractère séparateur de hiérarchie du serveur IMAP apparaît dans le nom de la mailbox, le serveur IMAP créera tous les boîtes parentes nécessaires pour créer la boîte donnée.

Par exemple, si vous essayez de créer "Projects/IMAP/Doc" dans un serveur dont le "/" est le caractère séparateur de hiérarchie, les éléments suivants seront créés :

Uniquement la boîte "Doc" si "Projects" & "IMAP" existent déjà.
Les boîtes "IMAP" & "Doc" si seule “Projects” existe déjà.
Les boîtes "Projects" & “IMAP” & "Doc" si elles n'existent pas déjà.

Dans le paramètre name, passez le nom de la mailbox à créer.

Objet retourné

La fonction retourne un objet décrivant le statut IMAP :

Propriété		Type	Description
success		Boolean	Vrai si l'opération est réussie, sinon Faux
statusText		Text	Message du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errors		Collection	Pile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
	[].errcode	Number	Code d'erreur 4D
	[].message	Text	Description de l'erreur 4D
	[].componentSignature	Text	Signature du composant interne qui a retourné l'erreur

Exemple

Pour créer une nouvelle boîte “Invoices” :

var $pw : text
var $options; $transporter; $status : object

$options:=New object

$pw:=Request("Please enter your password:")
If(OK=1)
$options.host:="imap.gmail.com"
$options.user:="test@gmail.com"
$options.password:=$pw

$transporter:=IMAP New transporter($options)

$status:=$transporter.createBox("Invoices")

If ($status.success)
ALERT("Mailbox creation successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if

.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éfinis dans 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 avec la fonction .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" //Mandatory
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=IMAP New transporter($server)

  //select mailbox
 $boxInfo:=$transporter.selectBox("Inbox")

  //get collection of message unique IDs
 $mailIds:=$transporter.searchMails("subject \"Reports\"")

  // Delete selected messages
 $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" //Mandatory
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=IMAP New transporter($server)

  //select mailbox
 $boxInfo:=$transporter.selectBox("Junk Email")

  // delete all messages in the current mailbox
 $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 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()retourne un objet boxInfo correspondant à la boîte de réception courante ou à la boîte de réception 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
mailUnseen	Number	Nombre de messages marqués "unseen"

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()retourne 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 ne renvoyer que les boîtes auxquelles vous êtes abonné False pour retourner toutes les boîtes aux lettres disponibles
names	Collection	Collection d'objets contenant un attribut "name" ou collection de textes contenant les noms de boîtes aux lettres
withBoxProperties	Boolean	Si true (par défaut) : ajoute les attributs `selectable`, `inferior` et `interesting` à l'objet de résultat. Si false, ces attributs sont omis.
withBoxInfo	Boolean	Valeur par défaut : False. Si true, ajoute les attributs `mailCount`, `mailRecent` et `id` à l'objet résultat.

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. Retourné si withBoxProperties=true ou withBoxInfo=true
[].selectable	Boolean	Indique si les droits d'accès permettent ou non de sélectionner la boîte aux lettres : true - la boîte aux lettres peut être sélectionnée false - la boîte aux lettres ne peut pas être sélectionnée Retourné si withBoxProperties=true
[].inferior	Boolean	Indique si les droits d'accès permettent ou non de créer une hiérarchie inférieure dans la boîte aux lettres : true - un niveau inférieur peut être créé false - un niveau inférieur ne peut pas être créé Retourné si withBoxProperties=true
[].interesting	Boolean	Indique si la boîte aux lettres a été marquée comme "intéressante" par le serveur : true - La boîte aux lettres a été marquée comme "intéressante" par le serveur. Par exemple, elle peut contenir de nouveaux messages. false - La boîte aux lettres n'a pas été marquée comme "intéressante" par le serveur . Retourné si withBoxProperties=true
[].mailCount	Number	Nombre de messages dans la boîte inbox. Retourné si withBoxInfo=true
[].mailRecent	Number	Nombre de messages portant le marqueur "recent" (indiquant les nouveaux messages). Retourné si withBoxInfo=true
[].mailUnseen	Number	Nombre de messages marqués "unseen". Retourné si withBoxInfo=true
[].id	Text	Identifiant unique de boîte aux lettres. Retourné si withBoxInfo=true

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()retourne 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 la durée maximale définie, 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

.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() retourne l'objet Email correspondant au msgNumber ou msgID dans la boite de réception désignée par l'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,

S'il n'y a pas de connexion ouverte, .getMail() ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de .selectBox()`.

Résultat

.getMail() retourne un objet Email avec les propriétés IMAP suivantes spécifiques : 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" //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")

  //get Email object with 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] (EmailObjectClass.md#objet-email) et une collection d'ID ou de numéros pour les messages manquants, le cas échéant

Description

La fonction .getMails()retourne 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 .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 - ID de messages passés précédemment 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 renvoyée si tous les messages ont été 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() retourne un BLOB avec le contenu MIME du message correspondant au msgNumber ou msgID dans la boîte de réception désignée par le IMAP_transporter.

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,

Si aucune boite de réception n'est sélectionnée avec .selectBox(), une erreur est générée,

S'il n'y a pas de connexion ouverte, .getMIMEAsBlob() ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de .selectBox().

Résultat

.getMIMEAsBlob() renvoie 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 : Object
 var $boxInfo : Variant
 var $blob : Blob
 var $transporter : 4D.IMAPTransporter

 $server:=New object
 $server.host:="imap.gmail.com"
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

  //create transporter
 $transporter:=IMAP New transporter($server)

  //select mailbox
 $boxInfo:=$transporter.selectBox("Inbox")

  //get BLOB
 $blob:=$transporter.getMIMEAsBlob(1)

.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 du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie. 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 $mailIds : Collection
 var $transporter : 4D.IMAPTransporter

 $server:=New object
 $server.host:="imap.gmail.com" //Mandatory
 $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 une collection d'IDs uniques de messages
 $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")

  // déplacer les messages trouvés de la boite courante vers la boite "documents"
 $status:=$transporter.move($mailIds;"documents")

Exemple 2

Pour déplacer 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" //Mandatory
 $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 courante vers la boite "documents"
 $status:=$transporter.move(IMAP all;"documents")

.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 de messages 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 $transporter : 4D.IMAPTransporter
 var $server;$boxInfo;$status : Object
 var $mailIds : Collection

 $server:=New object
 $server.host:="imap.gmail.com" //Mandatory
 $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 courante
 $status:=$transporter.delete($mailIds)

.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 (drapeaux) 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 renaming

Description

La fonction .renameBox() change le nom d'une boîte de réception 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)

// 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

.port

Historique

Release	Modifications
17 R4	Ajout

.port : Integer

Description

La propriété .port contient le numéro de port utilisé pour les transactions de courrier. 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 aux lettres 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 avec le marqueur \Flagged activé 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 dans la boîte de réception.
ANSWERED : Messages avec l'indicateur \Answered activé.
UNANSWERED : Messages pour lesquels l'indicateur \Answered n'est pas activé.
DELETED : Messages dont l'indicateur \Deleted est activé.
UNDELETED : Messages pour lesquels l'indicateur \Deleted n'a pas été activé.
DRAFT : Messages dont l'indicateur \Draft est activé.
UNDRAFT : Messages pour lesquels l'indicateur \Draft n'est pas activé.
FLAGGED : Messages avec le drapeau \Flagged activé.
UNFLAGGED : Messages pour lesquels l'indicateur \Flagged n'est pas activé.
RECENT : Messages dont l'indicateur \Recent est activé.
OLD : Messages pour lesquels l'indicateur \Recent n'a pas été activé.
SEEN : Messages pour lesquels l'indicateur \Seen est activé.
UNSEEN : Messages pour lesquels l'indicateur \Seen n'est pas activé.
NOUVEAU : Messages pour lesquels l'indicateur \Recent est activé mais pas l'indicateur \Seen. Equivaut à “(RECENT UNSEEN)”.
KEYWORD flag : Messages avec le jeu de mots-clés spécifié.
UNKEYWORD flag : Messages ne contenant pas le mot-clé 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 comprise dans la date spécifiée.
SINCE date : Messages dont la date interne est antérieure 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 compris dans la date spécifiée.
SENTSINCE date : Messages dont l'en-tête Date est inférieur ou supérieur à la date spécifiée.
TO string : Messages contenant la chaîne de caractères spécifiée dans l'en-tête TO.
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 qui contiennent la chaîne spécifiée dans l'en-tête Subject .
BODY string : Messages qui contiennent la chaîne spécifiée dans le body du message.
TEXT chaîne : Messages contenant la chaîne spécifiée dans l'en-tête ou dans le corps du message.
HEADER field-name string: Messages qui ont un en-tête avec le nom de champ spécifié et qui contiennent la chaîne spécifiée dans le field-body.
UID message-UID : Messages avec des identifiants uniques correspondant au jeu d'identifiants uniques spécifié.
LARGER n : Messages dont la taille est supérieure au nombre d'octets spécifié.
SMALLER n : Messages dont la taille est inférieure au nombre d'octets spécifié.
NOT search-key : Messages ne correspondant pas à la clé de recherche spécifiée.
OR search-key1 search-key2 : Messages qui correspondent à l'un des deux mots clés de recherche.

.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 boîte de réception name comme boîte de réception courante. Cette fonction vous permet de récupérer des informations sur la boite de réception.

Pour obtenir les informations d'une boîte aux lettres sans modifier la boîte aux lettres 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 la durée maximale définie (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 $server; $boxinfo : Object
 $server:=New object
 $server.host:="imap.gmail.com" //Obligatoire
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 var $transporter : 4D.IMAPTransporter
 $transporter:=IMAP New transporter($server)
 $boxInfo:=$transporter.selectBox("INBOX")

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 spécifiée à l'ensemble des boîtes 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

.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 boîte spécifiée de l'ensemble des boîtes 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

.user

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

La propriété .user contient le nom d'utilisateur utilisé pour l'authentification sur le serveur de messagerie.

Objet IMAP Transporter​

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()​

Description​

Exemple​

.port​

Description​

Objet IMAP Transporter

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()

Description

Exemple

.port

Description