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

IMAP New transporter

Historique
VersionModifications
v18 R4Ajout

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

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

|

Description

La commande IMAP New transporter configure une nouvelle connexion IMAP selon le paramètre server et renvoie un nouvel objet transporter. L'objet transporteur retourné sera alors utilisé pour la réception d'emails.

Dans le paramètre server, passez un objet contenant les propriétés suivantes :

serverValeur par défaut (si omise)
.acceptUnsecureConnection : Boolean    True si 4D est autorisé à établir une connexion non chiffréeFalse
.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 messageriele 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 serveur300
.connectionTimeOut : Integer    le temps d'attente maximal (en secondes) autorisé pour établir une connexion avec le serveur30
.host : Text    le nom ou l'adresse IP du serveur hôteobligatoire
.logFile : Text    le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexionaucun
.password : Text
Mot de passe utilisateur pour l'authentification sur le serveur. Non retourné en objet IMAP transporter.
aucun
.port : Integer     le numéro de port utilisé pour les transactions d'emails993
.user : Text     le nom d'utilisateur employé pour l'authentification sur le serveur de messagerieaucun

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

Résultat

La fonction retourne un objet IMAP transporter. Toutes les propriétés retournées sont en lecture seule.

La connexion IMAP est automatiquement fermée lorsque l'objet transporteur est détruit.

Exemple

$server:=New object
$server.host:="imap.gmail.com" //Obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$server.logFile:="LogTest.txt" //log à sauvegarder dans le dossier Logs

var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)

$status:=$transporter.checkConnection()
If(Not($status.success))
ALERT("An error occurred: "+$status.statusText)
End if

4D.IMAPTransporter.new()

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

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

|

Description

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

.acceptUnsecureConnection

Historique
VersionModifications
v17 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
VersionModifications
v20Prise en charge des mots-clés personnalisés (custom keywords)
v18 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
VersionModifications
v18 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 objet mailObj à la boîte destinationBox.

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

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

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

Propriété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, japonais (ISO-2022-JP) & Quoted-printable si possible, sinon UTF-8 & Quoted-printable
  • bodyCharset : US-ASCII si possible, japonais (ISO-2022-JP) et 7 bits si possible, sinon UTF-8 et Quoted-printable
mail mode 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
VersionModifications
v17 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
VersionModifications
v17 R4Ajout

.checkConnection() : Object

ParamètresTypeDescription
RésultatObject<-Statut de la connexion de l'objet transporteur

|

Description

La fonction .checkConnection() vérifie la connexion à l'aide des informations stockées dans l'objet transporteurrecrée la connexion si nécessaire, et renvoie son statut. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.

Objet retourné

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

Propriété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
VersionModifications
v18 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
VersionModifications
v17 R5Ajout

.connectionTimeOut : Integer

Description

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

.copy()

Historique
VersionModifications
v18 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 dans la destinationBox sur le serveur IMAP.

Vous pouvez passer :

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

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

Objet retourné

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

Propriété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
VersionModifications
v19Ajout

.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 mailbox avec le name passé en paramètre. Si le caractère séparateur de hiérarchie du serveur IMAP apparaît dans le nom de la mailbox, le serveur IMAP créera tous les boîtes parentes nécessaires pour créer la boîte donnée.

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

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

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

Objet retourné

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

Propriété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
VersionModifications
v18 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ésignés par msgsIDs ou allMsgs.

Vous pouvez passer :

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

L'exécution de cette fonction ne supprime pas réellement les messages. Les messages ayant le marqueur "deleted" peuvent toujours être trouvés par la fonction .searchMails(). Les messages marqués sont supprimés du serveur IMAP uniquement avec .expunge() ou en sélectionnant une autre boîte de réception ou lorsque l'objet transporter (créé avec IMAP New transporter) est détruit.

Objet retourné

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

Propriété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" //Obligatoire
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"

$transporter:=IMAP New transporter($server)

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

//obtenir la collection d'IDs unique des messages
$mailIds:=$transporter.searchMails("subject \"Reports\"")

// Supprimer les messages sélectionnés
$status:=$transporter.delete($mailIds)

Exemple 2

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

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

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

$transporter:=IMAP New transporter($server)

//selection de la boîte
$boxInfo:=$transporter.selectBox("Junk Email")

// suppression de tous les messages de la boîte courante
$status:=$transporter.delete(IMAP all)

.deleteBox()

Historique
VersionModifications
v19Ajout

.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
VersionModifications
v18 R6Ajout

.expunge() : Object

ParamètresTypeDescription
RésultatObject<-Statut de l'opération d'expunge

|

Description

La fonction .expunge() supprime tous les messages marqués "deleted" du serveur de messagerie IMAP. Le marqueur "deleted" peut être fixé avec les fonctions .delete() ou .addFlags().

Objet retourné

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

Propriété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
VersionModifications
v20id est renvoyé
v18 R5name est optionnel
v18 R4Ajout

.getBoxInfo( { name : Text }) : Object

ParamètresTypeDescription
nameText->Nom de la boîte de réception
RésultatObject<-Objet boxInfo

|

Description

La fonction .getBoxInfo() renvoie un objet boxInfo correspondant à la maibox courante ou à la mailbox nommée name. Cette fonction retourne les mêmes informations que .selectBox() mais sans modifier la boite de réception courante.

Dans le paramètre name passez le nom de la mailbox à laquelle vous souhaitez accéder. Le nom doit représenter une hiérarchie claire, de gauche à droite, avec des niveaux séparés par un caractère délimiteur spécifique. Le délimiteur peut être récupéré à l'aide de la fonction .getDelimiter().

Si la boîte de réception nommée name n'est pas sélectionnable ou n'existe pas, la fonction génère une erreur et retourne null.

Objet retourné

L'objet boxInfo contient les propriété suivantes :

Propriété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
VersionModifications
v18 R4Ajout
v19Ajout paramètre isSubscribed

.getBoxList( { parameters : Object } ) : Collection

ParamètresTypeDescription
parametersObject->Objet de paramètre
RésultatCollection<-Collection d'objets mailbox

|

Description

La fonction .getBoxList() renvoie une collection de boîtes aux lettres décrivant toutes les boîtes aux lettres disponibles. Cette fonction vous permet de gérer localement les listes de messages situés sur le serveur de messagerie IMAP.

Dans le paramètre optionnel parameters, passez un objet contenant des valeurs de filtrage des boîtes de réception retournées. Vous pouvez passer :

PropriétéTypeDescription
isSubscribedBoolean
  • True pour retourner uniquement les boîtes auxquelles vous êtes abonné
  • False pour retourner toutes les boîtes de réception disponibles
  • Résultat

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

    PropriétéTypeDescription
    [].nametextNom de la boîte de réception
    [].selectablebooleanIndique si les droits d'accès permettent ou non à la boite de réception d'être sélectionnée :
    • vrai - la boite de réception peut être sélectionnée
    • faux - la boite de réception ne peut pas être sélectionnée
    [].inferiorbooleanIndique si les droits d'accès permettent ou non la création d'une hiérarchie inférieure dans la boite de réception :
    • vrai - un niveau inférieur peut être créé
    • faux - un niveau inférieur ne peut pas être créé
    [].interestingbooleanIndique si la boite de réception a été marquée comme "intéressante" par le serveur :
    • vrai - la boite de réception a été marquée comme "intéressante" par le serveur. Par exemple, elle peut contenir de nouveaux messages.
    • faux - la boite de réception n'a pas été marquée comme "intéressante" par le serveur.

    Si le compte ne contient pas de boites de réception, une collection vide est retournée.

    • Si aucune connexion n'est ouverte, .getBoxList() ouvrira une connexion.
    • Si la connexion n'a pas été utilisée depuis le délai de connexion (voir IMAP New transporter), la fonction .checkConnection( ) est automatiquement appelée.

    Exemple

     var $transporter : 4D.IMAPTransporter
    $transporter:=IMAP New transporter($server)

    $boxList:=$transporter.getBoxList()

    For each($box;$boxList)
    If($box.interesting)
    $split:=Split string($box.name;$transporter.getDelimiter())
    ALERT("New emails are available in the box: "+$split[$split.length-1])
    End if
    End for each

    .getDelimiter()

    Historique
    VersionModifications
    v18 R4Ajout

    .getDelimiter() : Text

    ParamètresTypeDescription
    RésultatText<-Caractère de délimitation de hiérarchie

    |

    Description

    La fonction .getDelimiter() renvoie le caractère utilisé pour délimiter les niveaux de hiérarchie dans le nom de la boîte aux lettres.

    Le délimiteur est un caractère pouvant être utilisé pour :

    • créer des boites de réception de niveau inférieur
    • rechercher des niveaux inférieurs ou supérieurs dans la hiérarchie de la boite de réception

    Résultat

    Caractère de délimitation des noms de boites de réception.

    • Si aucune connexion n'est ouverte, .getDelimiter() ouvrira une connexion.
    • Si la connexion n'a pas été utilisée depuis le délai de connexion, la fonction

    Exemple

     var $transporter : 4D.IMAPTransporter
    $transporter:=IMAP New transporter($server)

    $boxList:=$transporter.getBoxList()

    For each($box;$boxList)
    If($box.interesting)
    $split:=Split string($box.name;$transporter.getDelimiter())
    ALERT("New emails are available in the box: "+$split[$split.length-1])
    End if
    End for each

    .getMail()

    Historique
    VersionModifications
    v18 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() renvoie l'objet Email correspondant au msgNumber ou msgID dans la boîte aux lettres désignée par IMAP_transporter. Cette fonction vous permet de gérer localement le contenu de l'email.

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

    • msgNumber, une valeur integer indiquant le numéro de séquence du message à récupérer ou
    • msgID, une valeur text indiquant l'ID unique du message à récupérer.

    Le paramètre facultatif options vous permet de passer un objet définissant des instructions supplémentaires pour la gestion de votre message. Les propriétés suivantes sont disponibles :

    Propriété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,
    • Si aucune connexion n'est ouverte, .getMail() ouvrira une connexion avec la dernière boite de réception spécifiée par .selectBox().

    Résultat

    .getMail() retourne un objet Email avec les propriétés IMAP supplémentaires suivantes : id, receivedAt et size.

    Exemple

    Vous souhaitez lire le message avec ID = 1 :

     var $server : Object
    var $info; $mail; $boxInfo : Variant
    var $transporter : 4D.IMAPTransporter

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

    //creation du transporter
    $transporter:=IMAP New transporter($server)

    //selection de la mailbox
    $boxInfo:=$transporter.selectBox("Inbox")

    //récupération de l'objet Email d'ID 1
    $mail:=$transporter.getMail(1)

    .getMails()

    Historique
    VersionModifications
    v18 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 et
    • une collection d'identifiants ou de numéros des messages manquants, le cas échéant

    |

    Description

    La fonction .getMails() renvoie un objet contenant une collection d'objets Email.

    Première syntaxe :

    .getMails( ids { ; options } ) -> result

    La première syntaxe vous permet de récupérer des messages en fonction de leurs identifiants.

    Dans le paramètre ids, passez une collection d'identifiants des messages à retourner. Vous pouvez obtenir les ID à l'aide de .getMail().

    Le paramètre optionnel options vous permet de définir les parties de messages à retourner. Pour une description détaillée des propriétés disponibles, reportez-vous au tableau Options ci-dessous.

    Deuxième syntaxe :

    .getMails( startMsg ; endMsg { ; options } ) -> result

    La deuxième syntaxe vous permet de récupérer des messages en fonction d'une plage séquentielle. Les valeurs passées représentent la position des messages dans la boite de réception.

    Dans le paramètre startMsg, passez une valeur integer correspondant au numéro du premier message dans la plage séquentielle. Si vous passez un nombre négatif (startMsg <= 0), le premier message de la boîte de réception sera utilisé comme début de la séquence.

    Dans le paramètre endMsg, passez une valeur integer correspondant au numéro du dernier message dans la plage séquentielle. Si vous passez un nombre négatif (endMsg <= 0), le dernier message de la boîte de réception sera utilisé comme fin de séquence.

    Le paramètre optionnel options vous permet de définir les parties de messages à retourner.

    Options

    Propriété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 la fonction .selectBox(), une erreur est générée.
    • S'il n'y a pas de connexion ouverte, .getMails() ouvrira une connexion avec la dernière boite de réception spécifiée à l'aide de .selectBox().

    Résultat

    .getMails() retourne un objet contenant les collections suivantes :

    PropriétéTypeDescription
    listeCollectionCollection d'objets Email. Si aucun objet Email n'est trouvé, une collection vide est retournée.
    notFoundCollectionCollection de :
    • première syntaxe - IDs de messages passés antérieurement qui n'existent pas
    • deuxième syntaxe - numéros de séquence des messages entre startMsg et endMsg qui n'existent pas
    Une collection vide est retournée si tous les messages sont trouvés.

    Exemple

    Vous souhaitez récupérer les 20 emails les plus récents sans modifier le statut "seen" :

     var $server,$boxInfo,$result : Object
    var $transporter : 4D.IMAPTransporter

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

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

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

    If($boxInfo.mailCount>0)
    // retrieve the headers of the last 20 messages without marking them as read
    $result:=$transporter.getMails($boxInfo.mailCount-20;$boxInfo.mailCount;\
    New object("withBody";False;"updateSeen";False))
    For each($mail;$result.list)
    // ...
    End for each
    End if

    .getMIMEAsBlob()

    Historique
    VersionModifications
    v18 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() copie les messages définis par msgsIDs ou allMsgs dans la destinationBox sur le serveur IMAP.

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

    • msgNumber, une valeur integer indiquant le numéro de séquence du message à récupérer ou
    • msgID, une valeur text indiquant l'ID unique du message à récupérer.

    Le paramètre optionnel updateSeen vous permet d'indiquer si le message est marqué comme "seen" (lu) dans la boîte de réception. Vous pouvez passer :

    • Vrai - pour marquer le message comme "seen" (indiquant que le message a été lu)
    • Faux - pour ne pas modifier le statut "seen" du message
      • La fonction retourne un BLOB vide si msgNumber ou msgID désigne un message inexistant,
      • var $pw : text var $options; $transporter; $status : object $options:=New object $pw:=Request("Please enter your password:") If(OK=1) $options.host:="imap.gmail.com" $options.user:="test@gmail.com" $options.password:=$pw $transporter:=IMAP New transporter($options) // rename mailbox $status:=$transporter.renameBox("Invoices"; "Bills") If ($status.success) ALERT("Mailbox renaming successful!") Else ALERT("Error: "+$status.statusText) End if End if Else ALERT("Error: "+$status.statusText) End if End if
      • var $pw; $name : text var $options; $transporter; $status : object $options:=New object $pw:=Request("Please enter your password:") If(OK=1) $options.host:="imap.gmail.com" $options.user:="test@gmail.com" $options.password:=$pw $transporter:=IMAP New transporter($options) $name:="Bills"+$transporter.getDelimiter()+"Atlas Corp" $status:=$transporter.unsubscribe($name) If ($status.success) ALERT("Mailbox unsubscription successful!") Else ALERT("Error: "+$status.statusText) End if End if Else ALERT("Error: "+$status.statusText) End if End if

    Résultat

    .getMIMEAsBlob() retourne un BLOB qui peut être archivé dans une base de données ou converti en un objet Email avec la commande MAIL Convert from MIME.

    Exemple

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

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

    $transporter:=IMAP New transporter($server)

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

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

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

    .host

    Historique
    VersionModifications
    v17 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
    VersionModifications
    v17 R5Ajout

    .logFile : Text

    Description

    La propriété .logFile contient le chemin complet du fichier d'historique qui a été défini (le cas échéant) pour la connexion. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

    Contrairement aux fichiers log habituels (activés via la commande SET DATABASE PARAMETER), les fichiers log étendus stockent le contenu MIME de tous les emails envoyés et n'ont pas de limite de taille. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

    .move()

    Historique
    VersionModifications
    v18 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 $transporter : 4D.IMAPTransporter

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

    $transporter:=IMAP New transporter($server)

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

    // déplacer tous les messages de la boite de réception courante vers la boite de réception "documents"
    $status:=$transporter.move(IMAP all;"documents")

    Exemple 2

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

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

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

    $transporter:=IMAP New transporter($server)

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

    //obtenir les IDs des 5 derniers messages reçus
    $mailIds:=$transporter.numToID(($boxInfo.mailCount-5);$boxInfo.mailCount)

    //supprimer les messages de la boite de réception courante
    $status:=$transporter.delete($mailIds)

    .numToID()

    Historique
    VersionModifications
    v18 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 uniques

    |

    Description

    La fonction .numToID() convertit les numéros de séquence en identifiants uniques IMAP pour les messages de la plage séquentielle désignée par startMsg et endMsg dans la boîte de réception courante.

    Dans le paramètre startMsg passez une valeur entier correspondant au numéro du premier message dans une plage séquentielle. Si vous passez un nombre négatif (startMsg <= 0), le premier message de la boîte de réception sera utilisé comme début de la séquence.

    Dans le paramètre endMsg passez une valeur entier long correspondant au numéro du dernier message à inclure dans une plage séquentielle. Si vous passez un nombre négatif (endMsg <= 0), le dernier message de la boîte de réception sera utilisé comme fin de séquence.

    Résultat

    La fonction retourne une collection de chaînes (IDs uniques).

    Exemple

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

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

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

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

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

    .removeFlags()

    Historique
    VersionModifications
    v20Prise en charge des mots-clés personnalisés (custom keywords)
    v18 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 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
    VersionModifications
    v19Ajout

    .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 de renommage

    |

    Description

    La fonction .renameBox() change le nom d'une boîte aux lettres sur le serveur IMAP. Essayer de renommer une mailbox qui n'existe pas ou de renommer une mailbox avec un nom qui est déjà utilisé génère une erreur.

    Dans le paramètre currentName, passez le nom de la mailbox à renommer.

    Passez le nouveau nom de la mailbox dans e paramètre newName.

    Objet retourné

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

    Propriété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)

    // rename mailbox
    $status:=$transporter.renameBox("Invoices"; "Bills")

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

    .port

    Historique
    VersionModifications
    v17 R4Ajout

    .port : Integer

    Description

    La propriété .port contient le numéro de port utilisé pour les transactions d'emails. Par défaut, si la propriété port n'a pas été définie dans l'objet server (utilisé pour créer l'objet transporteur avec SMTP New transporter, POP3 New transporter, IMAP New transporter), le port utilisé est :

    • SMTP - 587
    • POP3 - 995
    • IMAP - 993

    .searchMails()

    Historique
    VersionModifications
    v18 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 de réception courante. .

    searchCriteria est un paramètre texte listant un ou plusieurs critères de recherche (voir Mots-clés de recherche autorisés ci-dessous) associés ou non à des valeurs à rechercher. Un critère de recherche peut être composé d'un ou plusieurs éléments. Par exemple :

    SearchKey1 = FLAGGED
    SearchKey2 = NOT FLAGGED
    SearchKey3 = FLAGGED DRAFT

    La correspondance n'est généralement pas sensible à la casse

    • Si searchCriteria est une chaîne vide, la recherche sera équivalente à un "tout sélectionner".
    • Si searchCriteria contient plusieurs mots-clés de recherche, le résultat est l'intersection (fonction ET) de tous les messages qui correspondent à ces critères.
    searchCriteria = FLAGGED FROM "SMITH"

    ... retourne tous les messages comportant le marqueur \Flagged ET envoyés par Smith.

    • Vous pouvez utiliser les opérateurs OR ou NOT comme suit :
    searchCriteria = OR SEEN FLAGGED

    ... retourne tous les messages comportant le marqueur \Seen OU \Flagged

    searchCriteria = NOT SEEN

    ... retourne tous les messages ne comportant pas le marqueur \Seen.

    searchCriteria = HEADER CONTENT-TYPE "MIXED" NOT HEADER CONTENT-TYPE "TEXT"...

    ... retourne les messages dont l'en-tête content-type contient “Mixed” et ne contient pas “Text”.

    searchCriteria = HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED"

    ... retourne les messages dont l'en-tête content-type contient “ e ” et dont l'en-tête Subject ne contient pas “ o ” et dont l'en-tête content-type n'est pas “ Mixed ”.

    A noter que dans les deux derniers exemples, le résultat de la recherche est différent lorsque vous enlevez les parenthèses de la première liste de mots-clés.

    • Le paramètre searchCriteria peut inclure optionnellement l'instruction [CHARSET]. Cette instruction est composée du mot "CHARSET" suivi d'un jeu de caractères défini [CHARSET] (US ASCII, ISO-8859). Elle indique le codage de caractères utilisé dans la chaine searchCriteria. Par conséquent, vous devez convertir la chaîne searchCriteria dans le jeu de caractères spécifié si vous utilisez l'instruction [CHARSET] (voir les commandes CONVERT FROM TEXT ou Convert to text). Par défaut, 4D encode la chaîne de critères searchCriteria en "Quotable Printable" si elle contient des caractères étendus.
    searchCriteria = CHARSET "ISO-8859" BODY "Help"

    signifie que le critère de recherche utilise le jeu de caractères iso-8859 et que le serveur devra convertir la chaîne avant la recherche, si nécessaire.

    Mots-clés de recherche autorisés

    Les mots-clés de recherche peuvent traiter des valeurs des types suivants :

    • Valeurs de type date : Les valeurs de type date sont placées dans des chaînes formatées de la manière suivante : date-day+"-"+date-month+"-"+date-year où date-day indique la date du jour dans le mois (2 caractères maxi), date-month indique le mois (Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Dec) et date-year indique l’année sur 4 chiffres. Exemple : searchCriteria = SENTBEFORE 1-Feb-2020 (il n’est généralement pas nécessaire de mettre une date entre guillemets puisqu’elle ne contient pas de caractères spéciaux)

    • Valeurs de type chaîne : Les valeurs de type chaîne peuvent contenir tout type de caractère et doivent être placées entre des guillemets. Toutefois, si la chaîne ne contient pas de caractères spéciaux (des espaces par exemple), les guillemets ne sont pas obligatoires. Dans tous les cas, les guillemets vous permettent de vous assurer que la chaîne sera correctement interprétée. Example: searchCriteria = FROM "SMITH" For all search keys that use strings, a message matches the key if the string is a substring of the field. La recherche ne tient pas compte de la casse des caractères.

    • Noms de champs : Les valeurs de type nom de champ contiennent le nom d’un champ d’en-tête. Exemple : searchCriteria = HEADER CONTENT-TYPE "MIXED"

    • Marqueurs : Les valeurs de type marqueur (flags) acceptent un ou plusieurs mots-clés (y compris des marqueurs standard) séparés par des espaces. Exemple : searchCriteria = KEYWORD \Flagged \Draft

    • Ensemble de messages : Les valeurs de ce type désignent un ensemble de messages. Elles contiennent une liste de numéros de messages dans un ordre croissant, de 1 au nombre total de messages dans la boîte aux lettres. Les numéros sont séparés par des virgules ; un deux-points (:) indique un intervalle (inclusif) de numéros. Examples: 2,4:7,9,12:* is 2,4,5,6,7,9,12,13,14,15 for a mailbox with 15 messages. searchCriteria = 1:5 ANSWERED recherche, parmi les messages 1 à 5, ceux qui comportent le marqueur \Answered. searchCriteria= 2,4 ANSWERED recherche, parmi les messages 2 et 4, ceux qui comportent le marqueur \Answered.

    Mots-clés de recherche autorisés

    ALL: Tous les messages de la boîte de réception.
    ANSWERED: Messages comportant le marqueur \Answered.
    UNANSWERED: Messages ne comportant pas le marqueur \Answered.
    DELETED: Messages comportant le marqueur \Deleted.
    UNDELETED: Messages ne comportant pas le marqueur \Deleted.
    DRAFT: Messages comportant le marqueur \Draft.
    UNDRAFT: Messages ne comportant pas le marqueur \Draft.
    FLAGGED: Messages comportant le marqueur \Flagged.
    UNFLAGGED: Messages ne comportant pas le marqueur \Flagged.
    RECENT: Messages comportant le marqueur \Recent.
    OLD: Messages ne comportant pas le marqueur \Recent.
    SEEN: Messages comportant le marqueur \Seen.
    UNSEEN: Messages ne comportant pas le marqueur \Seen.
    NEW: Messages comportant le marqueur \Recent et pas le marqueur \Seen. Equivaut à “(RECENT UNSEEN)”.
    KEYWORD flag** : Messages comportant le marqueur spécifié.
    UNKEYWORD flag**: Messages ne comportant pas le marqueur spécifié.
    BEFORE date**: Messages dont la date interne est antérieure à la date spécifiée.
    ON date**: Messages dont la date interne est égale à la date spécifiée.
    SINCE date**: Messages dont la date interne est égale ou postérieure à la date spécifiée.
    SENTBEFORE date**: Messages dont l’en-tête Date est antérieur à la date spécifiée.
    SENTON date**: Messages dont l’en-tête Date est égal à la date spécifiée.
    SENTSINCE date**: Messages dont l’en-tête Date est égal ou postérieur à la date spécifiée.
    TO string**: Messages contenant la chaîne spécifiée dans l’en-tête Destinataire.
    FROM string**: Messages contenant la chaîne spécifiée dans l’en-tête Emetteur.
    CC string**: Messages contenant la chaîne spécifiée dans l’en-tête CC.
    BCC string**: Messages contenant la chaîne spécifiée dans l’en-tête BCC.
    SUBJECT string**: Messages contenant la chaîne spécifiée dans l’en-tête Objet.
    BODY string**: Messages dont le corps contient la chaîne spécifiée.
    TEXT string**: Messages contenant la chaîne spécifiée dans l’en-tête ou le corps.
    HEADER field-name* *string**: Messages dont l’en-tête contient le champ défini et dont ce champ contient la chaîne définie.
    UID message-UID**: Messages dont le numéro unique correspond à la valeur spécifiée.
    LARGER n**: Messages dont la taille en octets est supérieure à la taille spécifiée.
    SMALLER n**: Messages dont la taille en octets est inférieure à la taille spécifiée.
    NOT search-key**: Messages ne correspondant pas au critère spécifié.
    OR search-key1* *search-key2**: Messages correspondant au premier ou au deuxième critère spécifié.

    .selectBox()

    Historique
    VersionModifications
    v20id, flags, permanentFlags sont renvoyés
    v18 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 mailbox name comme boîte aux lettres courante. Cette fonction vous permet de récupérer des informations sur la boite de réception.

    Pour lire les informations à partir d'une mailbox sans changer la mailbox courante, utilisez .getBoxInfo().

    Dans le paramètre optionnel name passez le nom de la boite de réception à laquelle vous souhaitez accéder. Le nom doit représenter une hiérarchie claire, de gauche à droite, avec des niveaux séparés par un caractère délimiteur spécifique. Le délimiteur peut être récupéré à l'aide de la fonction .getDelimiter().

    Le paramètre optionnel state définit le type d'accès à la mailbox. Les valeurs possibles sont les suivantes :

    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 le délai de connexion (voir IMAP New transporter), la fonction .checkConnection( ) est automatiquement appelée.

    Objet retourné

    L'objet boxInfo contient les propriété suivantes :

    Propriété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 $pw; $name : text
    var $options; $transporter; $status : object

    $options:=New object

    $pw:=Request("Please enter your password:")

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

    $transporter:=IMAP New transporter($options)

    $name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
    $status:=$transporter.subscribe($name)

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

    .subscribe()

    Historique
    VersionModifications
    v19Ajout

    .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 aux lettres spécifiée à l'ensemble des mailboxes auxquelles vous avez "souscrit" sur le serveur IMAP. Ainsi, vous pouvez contrôler la taille de la liste des boîtes de réception disponibles en souscrivant uniquement à celles que vous souhaitez généralement consulter.

    Dans le paramètre name, passez le nom de la mailbox à ajouter (subscribe) à la liste de mailboxes auxquelles vous avez "souscrit".

    Objet retourné

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

    Propriété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
    Else
    ALERT("Error: "+$status.statusText)
    End if
    End if
    Else
    ALERT("Error: "+$status.statusText)
    End if
    End if

    .unsubscribe()

    Historique
    VersionModifications
    v19Ajout

    .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 mailbox spécifiée de l'ensemble des mailboxes auxquelles vous avez "souscrit". Elle vous permet de réduire le nombre de mailboxes que vous consultez régulièrement.

    Dans le paramètre name, passez le nom de la mailbox à supprimer (unsubscribe) de la liste de mailboxes auxquelles vous avez "souscrit".

    Objet retourné

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

    Propriété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
    Else
    ALERT("Error: "+$status.statusText)
    End if
    End if

    .user

    Historique
    VersionModifications
    v17 R4Ajout

    .user : Text

    Description

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