Aller au contenu principal
Version: 20 R5

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

IMAP New transporter

Historique
ReleaseModifications
18 R4Ajout

IMAP New transporter( server : Object ) : 4D.IMAPTransporter

ParamètresTypeDescription
serverObject->Informations sur le serveur IMAP
Résultat4D.IMAPTransporter<-Objet transporteur IMAP

Description

La commande IMAP New transporterconfigure une nouvelle connexion IMAP en fonction du paramètre server et retourne 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 :

serverValeur 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 maximum (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 du fichier journal étendu défini (le cas échéant) pour la connexion de messagerie
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 de courrier
993
.user : Text
le nom d'utilisateur utilisé 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 transporteur IMAP. 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ètresTypeDescription
serverObject->Informations sur le serveur IMAP
Résultat4D.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
ReleaseModifications
17 R4Ajout

.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
ReleaseModifications
20Prise en charge des mots-clés personnalisés (custom keywords)
18 R6Ajout

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

ParamètresTypeDescription
msgIDsCollection->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
keywordsObject->Mots-clés de flags à ajouter
RésultatObject<-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 :
ConstanteValeurCommentaire
IMAP all1Sé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éTypeDescription
$draftBooleanTrue pour ajouter le marqueur "draft" au message
$seenBooleanTrue pour ajouter le marqueur "seen" au message
$flaggedBooleanTrue pour ajouter le marqueur "flagged" au message
$answeredBooleanTrue pour ajouter le marqueur "answered" au message
$deletedBooleanTrue pour ajouter le marqueur "deleted" au message
<custom flag>BooleanTrue 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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
18 R6Ajout

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

ParamètresTypeDescription
mailObjObject->Objet email
destinationBoxText->Mailbox devant recevoir l'objet email
optionsObject->Objet contenant les informations de charset
RésultatObject<-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éTypeDescription
headerCharsetTextCharset 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
bodyCharsetTextCharset 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 :

ConstanteValeurCommentaire
mail mode ISO2022JPUS-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 ISO88591ISO-8859-1
  • headerCharset : ISO-8859-1 & Quoted-printable
  • bodyCharset : ISO-8859-1 & 8-bit
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64

Objet retourné

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

PropriétéTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
17 R4Ajout

.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 :

ValeurConstantesCommentaire
CRAM-MD5IMAP authentication CRAM MD5Authentification à l'aide du protocole CRAM-MD5
LOGINIMAP authentication loginAuthentification à l'aide du protocole LOGIN
OAUTH2IMAP authentication OAUTH2Authentification à l'aide du protocole OAuth2
PLAINIMAP authentication plainAuthentification à l'aide du protocole PLAIN

.checkConnection()

Historique
ReleaseModifications
17 R4Ajout

.checkConnection() : Object

ParamètresTypeDescription
RésultatObject<-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éTypeDescription
successbooleanVrai si la vérification a été effectuée avec succès, sinon Faux
statusnumber(SMTP uniquement) Code du statut retourné par le serveur de messagerie (0 en cas de problème non lié au traitement du mail)
statusTexttextMessage du statut retourné par le serveur de messagerie, ou dernière erreur retournée dans la pile d'erreurs 4D
errorscollectionPile d'erreurs 4D (non retournée si une réponse du serveur de messagerie est reçue)
[ ].errCodenumberCode d'erreur 4D
[ ].messagetextDescription de l'erreur 4D
[ ].componentSignaturetextSignature du composant interne qui a retourné l'erreur

.checkConnectionDelay

Historique
ReleaseModifications
18 R4Ajout

.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
ReleaseModifications
17 R5Ajout

.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
ReleaseModifications
18 R5Ajout

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

ParamètresTypeDescription
msgsIDsCollection->Collection d'IDs uniques de messages (texte)
allMsgsInteger->IMAP all : tous les messages de la boîte de réception sélectionnée
destinationBoxText->Boîte de réception recevant les messages copiés
RésultatObject<-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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
19Ajout

.createBox( name : Text ) : Object

ParamètresTypeDescription
nameText->Nom de la nouvelle mailbox
RésultatObject<-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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
18 R5Ajout

.delete( msgsIDs : Collection ) : Object
.delete( allMsgs : Integer ) : Object

ParamètresTypeDescription
msgsIDsCollection->Collection d'IDs uniques de messages (texte)
allMsgsInteger->IMAP all : tous les messages de la boîte de réception sélectionnée
RésultatObject<-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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
19Ajout

.deleteBox( name : Text ) : Object

ParamètresTypeDescription
nameText->Nom de la boîte de réception à supprimer
RésultatObject<-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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
18 R6Ajout

.expunge() : Object

ParamètresTypeDescription
RésultatObject<-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éTypeDescription
successBooleanVrai si l'opération est réussie, sinon Faux
statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
[].errcodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature 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
ReleaseModifications
20id est renvoyé
18 R5name est optionnel
18 R4Ajout

.getBoxInfo( { name : Text }) : Object

ParamètresTypeDescription
nameText->Nom de la boîte de réception
RésultatObject<-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éTypeDescription
nametextNom de la boîte de réception
mailCountnumberNombre de messages contenus dans la boîte de réception
mailRecentnumberNombre de messages portant le marqueur "récent" (indiquant les nouveaux messages)
idtextIdentifiant 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
ReleaseModifications
18 R4Ajout
19Ajout paramètre isSubscribed

.getBoxList( { parameters : Object } ) : Collection

ParamètresTypeDescription
parametersObject->Objet de paramètre
RésultatCollection<-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éTypeDescription
isSubscribedBoolean
  • True pour ne renvoyer que les boîtes auxquelles vous êtes abonné
  • False pour retourner toutes les boîtes aux lettres disponibles
  • Résultat

    Chaque objet de la collection retournée contient les propriétés suivantes :

    PropriétéTypeDescription
    [].nametextNom de la boîte de réception
    [].selectablebooleanIndique 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
    [].inferiorbooleanIndique 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éé
    [].interestingbooleanIndique 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
    • .

    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
    ReleaseModifications
    18 R4Ajout

    .getDelimiter() : Text

    ParamètresTypeDescription
    RésultatText<-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
    ReleaseModifications
    18 R4Ajout

    .getMail( msgNumber: Integer { ; options : Object } ) : Object
    .getMail( msgID: Text { ; options : Object } ) : Object

    ParamètresTypeDescription
    msgNumberInteger->Numéro de séquence du message
    msgIDText->ID unique du message
    optionsObject->Instructions sur la gestion du message
    RésultatObject<-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éTypeDescription
    updateSeenbooleanSi 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
    withBodybooleanPassez 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
    ReleaseModifications
    18 R5Ajout

    .getMails( ids : Collection { ; options : Object } ) : Object
    .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object

    ParamètresTypeDescription
    idsCollection->Collection d'identifiants de messages
    startMsgInteger->Numéro de séquence du premier message
    endMsgInteger->Numéro de séquence du dernier message
    optionsObject->Instructions sur la gestion du message
    RésultatObject<-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éTypeDescription
    updateSeenBooleanSi 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
    withBodyBooleanPassez 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éTypeDescription
    listeCollectionCollection d'objets Email. Si aucun objet Email n'est trouvé, une collection vide est retournée.
    notFoundCollectionCollection 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
    ReleaseModifications
    18 R4Ajout

    .getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob
    .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob

    ParamètresTypeDescription
    msgNumberInteger->Numéro de séquence du message
    msgIDText->ID unique du message
    updateSeenBoolean->Si Vrai, le message est marqué comme "seen" (lu) dans la boite de réception. Si Faux, le message demeure inchangé.
    RésultatBLOB<-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
    ReleaseModifications
    17 R5Ajout

    .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
    ReleaseModifications
    17 R5Ajout

    .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 à :

    .move()

    Historique
    ReleaseModifications
    18 R5Ajout

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

    ParamètresTypeDescription
    msgsIDsCollection->Collection d'IDs uniques de messages (texte)
    allMsgsInteger->IMAP all : tous les messages de la boîte de réception sélectionnée
    destinationBoxText->Boîte de réception recevant les messages déplacés
    RésultatObject<-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éTypeDescription
    successBooleanVrai si l'opération est réussie, sinon Faux
    statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
    errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
    [].errcodeNumberCode d'erreur 4D
    [].messageTextDescription de l'erreur 4D
    [].componentSignatureTextSignature 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
    ReleaseModifications
    18 R5Ajout

    .numToID( startMsg : Integer ; endMsg : Integer ) : Collection

    ParamètresTypeDescription
    startMsgInteger->Numéro de séquence du premier message
    endMsgInteger->Numéro de séquence du dernier message
    RésultatCollection<-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
    ReleaseModifications
    20Prise en charge des mots-clés personnalisés (custom keywords)
    18 R6Ajout

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

    ParamètresTypeDescription
    msgIDsCollection->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
    keywordsObject->Mots-clés de flags à supprimer
    RésultatObject<-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 :
    ConstanteValeurCommentaire
    IMAP all1Sé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ètresTypeDescription
    $draftBooleanTrue pour supprimer le marqueur "draft" du message
    $seenBooleanTrue pour supprimer le marqueur "seen" du message
    $flaggedBooleanTrue pour supprimer le marqueur "flagged" du message
    $answeredBooleanTrue pour supprimer le marqueur "answered" du message
    $deletedBooleanTrue pour supprimer le marqueur "deleted" du message
    <custom flag>BooleanTrue 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éTypeDescription
    successBooleanVrai si l'opération est réussie, sinon Faux
    statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
    errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
    [].errcodeNumberCode d'erreur 4D
    [].messageTextDescription de l'erreur 4D
    [].componentSignatureTextSignature 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
    ReleaseModifications
    19Ajout

    .renameBox( currentName : Text ; newName : Text ) : Object

    ParamètresTypeDescription
    currentNameText->Nom actuel de la boîte de réception
    nouveauNomText->Nom de la nouvelle mailbox
    RésultatObject<-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éTypeDescription
    successBooleanVrai si l'opération est réussie, sinon Faux
    statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
    errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
    [].errcodeNumberCode d'erreur 4D
    [].messageTextDescription de l'erreur 4D
    [].componentSignatureTextSignature 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
    ReleaseModifications
    17 R4Ajout

    .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
    ReleaseModifications
    18 R5Ajout

    .searchMails( searchCriteria : Text ) : Collection

    ParamètresTypeDescription
    searchCriteriaText->Critère(s) de recherche
    RésultatCollection<-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
    ReleaseModifications
    20id, flags, permanentFlags sont renvoyés
    18 R4Ajout

    .selectBox( name : Text { ; state : Integer } ) : Object

    ParamètresTypeDescription
    nameText->Nom de la boîte de réception
    stateInteger->Statut de l'accès à la boite de réception
    RésultatObject<-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 :

    ConstanteValeurCommentaire
    IMAP read only state1La 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 state0La 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éTypeDescription
    nameTextNom de la boîte de réception
    mailCountnumberNombre de messages contenus dans la boîte de réception
    mailRecentnumberNombre de messages avec le marqueur "recent"
    idtextIdentifiant unique de la boîte aux lettres
    flagstextListe des flags actuellement utilisés pour la boîte aux lettres, séparés par des espaces
    permanentFlagstextListe 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")

    .subscribe()

    Historique
    ReleaseModifications
    19Ajout

    .subscribe( name : Text ) : Object

    ParamètresTypeDescription
    nameText->Nom de la boîte de réception
    RésultatObject<-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éTypeDescription
    successBooleanVrai si l'opération est réussie, sinon Faux
    statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
    errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
    [].errcodeNumberCode d'erreur 4D
    [].messageTextDescription de l'erreur 4D
    [].componentSignatureTextSignature 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
    ReleaseModifications
    19Ajout

    .unsubscribe( name : Text ) : Object

    ParamètresTypeDescription
    nameText->Nom de la boîte de réception
    RésultatObject<-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éTypeDescription
    successBooleanVrai si l'opération est réussie, sinon Faux
    statusTextTextMessage du statut retourné par le serveur IMAP, ou dernière erreur retournée dans la pile d'erreurs 4D
    errorsCollectionPile d'erreurs 4D (non retournée si une réponse du serveur IMAP est reçue)
    [].errcodeNumberCode d'erreur 4D
    [].messageTextDescription de l'erreur 4D
    [].componentSignatureTextSignature 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
    ReleaseModifications
    17 R4Ajout

    .user : Text

    Description

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