Version: 20 R5 BETA

IMAPTransporter

The IMAPTransporter class allows you to retrieve messages from a IMAP email server.

Objet IMAP Transporter

IMAP Transporter objects are instantiated with the IMAP New transporter command. Leurs propriétés et fonctions sont les suivantes :


.acceptUnsecureConnection : Boolean True if 4D is allowed to establish an unencrypted connection
.addFlags( msgIDs : Collection ; keywords : Object ) : Object .addFlags( msgIDs : Text ; keywords : Object ) : Object .addFlags( msgIDs : Longint ; keywords : Object ) : Object adds flags to the `msgIDs` for the specified `keywords`
.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object appends a `mailObj` to the `destinationBox`
.authenticationMode : Text the authentication mode used to open the session on the mail server
.checkConnection() : Object checks the connection using information stored in the transporter object
.checkConnectionDelay : Integer the maximum time (in seconds) allowed prior to checking the connection to the server
.connectionTimeOut : Integer the maximum wait time (in seconds) allowed to establish a connection to the server
.copy( msgsIDs : Collection ; destinationBox : Text ) : Object .copy( allMsgs : Integer ; destinationBox : Text ) : Object copies the messages defined by msgsIDs or allMsgs to the destinationBox on the IMAP server
.createBox( name : Text ) : Object creates a mailbox with the given `name`
.delete( msgsIDs : Collection ) : Object .delete( allMsgs : Integer ) : Object sets the "deleted" flag for the messages defined in `msgsIDs` or `allMsgs`
.deleteBox( name : Text ) : Object permanently removes the mailbox with the given `name` from the IMAP server
.expunge() : Object removes all messages with the "deleted" flag from the IMAP mail server.
.getBoxInfo( { name : Text }) : Object returns a `boxInfo` object corresponding to the current maibox, or the mailbox name
.getBoxList( { parameters : Object } ) : Collection returns a collection of mailboxes describing all of the available mailboxes
.getDelimiter() : Text returns the character used to delimit levels of hierarchy in the mailbox name
.getMail( msgNumber: Integer { ; options : Object } ) : Object .getMail( msgID: Text { ; options : Object } ) : Object returns the `Email` object corresponding to the msgNumber or msgID in the mailbox designated by the `IMAP_transporter`
.getMails( ids : Collection { ; options : Object } ) : Object .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object returns an object containing a collection of `Email` objects
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob returns a BLOB containing the MIME contents for the message corresponding to the msgNumber or msgID in the mailbox designated by the `IMAP_transporter`
.host : Text the name or the IP address of the host server
.logFile : Text the path of the extended log file defined (if any) for the mail connection
.move( msgsIDs : Collection ; destinationBox : Text ) : Object .move( allMsgs : Integer ; destinationBox : Text ) : Object moves the messages defined by msgsIDs or allMsgs to the destinationBox on the IMAP server
.numToID( startMsg : Integer ; endMsg : Integer ) : Collection converts the sequence numbers to IMAP unique IDs for the messages in the sequential range designated by startMsg and endMsg
.removeFlags( msgIDs : Collection ; keywords : Object ) : Object .removeFlags( msgIDs : Text ; keywords : Object ) : Object .removeFlags( msgIDs : Longint ; keywords : Object ) : Object removes flags from the `msgIDs` for the specified `keywords`
.renameBox( currentName : Text ; newName : Text ) : Object changes the name of a mailbox on the IMAP server
.port : Integer the port number used for mail transactions
.searchMails( searchCriteria : Text ) : Collection searches for messages that match the given searchCriteria in the current mailbox
.selectBox( name : Text { ; state : Integer } ) : Object selects the name mailbox as the current mailbox
.subscribe( name : Text ) : Object allows adding or removing of the specified mailbox to/from the IMAP server’s set of “subscribed” mailboxes
.unsubscribe( name : Text ) : Object removes a mailbox from a set of subscribed mailboxes
.user : Text the user name used for authentication on the mail server

IMAP New transporter

Historique

Release	Modifications
18 R4	Ajout

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

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

Description

The IMAP New transporter command configures a new IMAP connection according to the server parameter and returns a new transporter object. L'objet transporteur retourné sera alors utilisé pour la réception d'emails.

In the server parameter, pass an object containing the following properties:

server	Valeur par défaut (si omise)
.acceptUnsecureConnection : Boolean True if 4D is allowed to establish an unencrypted connection	False
.accessTokenOAuth2: Text .accessTokenOAuth2: Object Text string or token object representing OAuth2 authorization credentials. Used only with OAUTH2 `authenticationMode`. If `accessTokenOAuth2` is used but `authenticationMode` is omitted, the OAuth 2 protocol is used (if allowed by the server). Not returned in IMAP transporter object.	aucun
.authenticationMode : Text the authentication mode used to open the session on the mail server	le mode d'authentification le plus sûr pris en charge par le serveur est utilisé
.checkConnectionDelay : Integer the maximum time (in seconds) allowed prior to checking the connection to the server	300
.connectionTimeOut : Integer the maximum wait time (in seconds) allowed to establish a connection to the server	30
.host : Text the name or the IP address of the host server	obligatoire
.logFile : Text the path of the extended log file defined (if any) for the mail connection	aucun
.password : Text User password for authentication on the server. Not returned in IMAP transporter object.	aucun
.port : Integer the port number used for mail transactions	993
.user : Text the user name used for authentication on the mail server	aucun

Warning: Make sure the defined timeout is lower than the server timeout, otherwise the client timeout will be useless.

Résultat

The function returns an IMAP transporter object. All returned properties are read-only.

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

Exemple

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

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

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

4D.IMAPTransporter.new()

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

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

Description

The 4D.IMAPTransporter.new() function creates and returns a new object of the 4D.IMAPTransporter type. It is identical to the IMAP New transporter command (shortcut).

.acceptUnsecureConnection

Historique

Release	Modifications
17 R4	Ajout

.acceptUnsecureConnection : Boolean

Description

The .acceptUnsecureConnection property contains True if 4D is allowed to establish an unencrypted connection when encrypted connection is not possible.

It contains False if unencrypted connections are unallowed, in which case an error in returned when encrypted connection is not possible.

Ports sécurisés disponibles :

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

.addFlags()

Historique

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

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

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

Description

The .addFlags() function adds flags to the msgIDs for the specified keywords.

In the msgIDs parameter, you can pass either:

a collection containing the unique IDs of specific messages or
the unique ID (text) of a single message or
the following constant (longint) for all messages in the selected mailbox:

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

The keywords parameter lets you define the flags to add to msgIDs. Vous pouvez utiliser les flags standard suivants ainsi que des flags personnalisés (la prise en charge des flags personnalisés dépend de l'implémentation du serveur) :

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

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

Pour qu'un mot-clé soit pris en compte, il doit être à vrai.
L'interprétation des indicateurs de mots-clés peut varier selon le client de messagerie.

Returned object

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

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

Exemple

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

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

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

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

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

.append()

Historique

Release	Modifications
18 R6	Ajout

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

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

Description

The .append() function appends a mailObj to the destinationBox.

In the mailObj parameter, pass an Email object. For a comprehensive description of mail properties, see Email object. The .append() function supports keyword tags in the Email object's keywords attribute.

The optional destinationBox parameter lets you pass the name of a mailbox where the mailObj will be appended. S'il est omis, la mailbox courante sera utilisée.

In the optional options parameter, you can pass an object to define the charset and encoding for specific parts of the email. Propriétés disponibles :

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

Charsets possibles :

Constante	Valeur	Commentaire
mail mode ISO2022JP	US-ASCII_ISO-2022-JP_UTF8_QP	headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise UTF-8 & Quoted-printable
mail mode ISO88591	ISO-8859-1	headerCharset: ISO-8859-1 & Quoted-printable bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8	US-ASCII_UTF8_QP	headerCharset & bodyCharset : US-ASCII si possible, sinon UTF-8 & Quoted-printable (valeur par défaut)
mail mode UTF8 in base64	US-ASCII_UTF8_B64	headerCharset &bodyCharset : US-ASCII si possible, sinon UTF-8 & base64

Returned object

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

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

Exemple

Pour enregistrer un email dans la boîte Drafts :

var $settings; $status; $msg; $imap: Object

$settings:=New object("host"; "domain.com"; "user"; "xxxx"; "password"; "xxxx"; "port"; 993)

$imap:=IMAP New transporter($settings)

$msg:=New object
$msg.from:="xxxx@domain.com"
$msg.subject:="Lorem Ipsum"
$msg.textBody:="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
$msg.keywords:=New object
$msg.keywords["$seen"]:=True//flag the message as read
$msg.keywords["$draft"]:=True//flag the message as a draft

$status:=$imap.append($msg; "Drafts")

.authenticationMode

Historique

Release	Modifications
17 R4	Ajout

.authenticationMode : Text

Description

The .authenticationMode property contains the authentication mode used to open the session on the mail server.

Par défaut, le mode le plus sécurisé pris en charge par le serveur est utilisé.

Valeurs possibles :

Valeur	Constantes	Commentaire
CRAM-MD5	`IMAP authentication CRAM MD5`	Authentification à l'aide du protocole CRAM-MD5
LOGIN	`IMAP authentication login`	Authentification à l'aide du protocole LOGIN
OAUTH2	`IMAP authentication OAUTH2`	Authentification à l'aide du protocole OAuth2
PLAIN	`IMAP authentication plain`	Authentification à l'aide du protocole PLAIN

.checkConnection()

Historique

Release	Modifications
17 R4	Ajout

.checkConnection() : Object

Paramètres	Type		Description
Résultat	Object	<-	Statut de la connexion de l'objet transporteur

Description

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. Cette fonction vous permet de vérifier que les valeurs fournies par l'utilisateur sont valides et cohérentes.

Objet retourné

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

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

.checkConnectionDelay

Historique

Release	Modifications
18 R4	Ajout

.checkConnectionDelay : Integer

Description

The .checkConnectionDelay property contains the maximum time (in seconds) allowed prior to checking the connection to the server. Si cette durée est dépassée entre deux appels de méthodes, la connexion au serveur sera vérifiée. By default, if the property has not been set in the server object, the value is 300.

Warning: Make sure the defined timeout is lower than the server timeout, otherwise the client timeout will be useless.

.connectionTimeOut

Historique

Release	Modifications
17 R5	Ajout

.connectionTimeOut : Integer

Description

The .connectionTimeOut property contains the maximum wait time (in seconds) allowed to establish a connection to the server. By default, if the property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, or IMAP New transporter), the value is 30.

.copy()

Historique

Release	Modifications
18 R5	Ajout

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

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

Description

The .copy() function copies the messages defined by msgsIDs or allMsgs to the destinationBox on the IMAP server.

Vous pouvez passer :

in the msgsIDs parameter, a collection containing the unique IDs of the specific messages to copy, or
in the allMsgs parameter, the IMAP all constant (integer) to copy all messages in the selected mailbox.

The destinationBox parameter allows you to pass a text value with the name of the mailbox where the copies of messages will be placed.

Returned object

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

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

Exemple 1

Pour copier une sélection de messages :

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

 $server:=New object
 $server.host:="imap.gmail.com" //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 \"4D new feature:\"")

  // copy found messages to the "documents" mailbox
 $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" //Mandatory
 $server.port:=993
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

 $transporter:=IMAP New transporter($server)

  //select mailbox

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

  // copy all messages to the "documents" mailbox
 $status:=$transporter.copy(IMAP all;"documents")

.createBox()

Historique

Release	Modifications
19	Ajout

.createBox( name : Text ) : Object

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

Description

The .createBox() function creates a mailbox with the given name. 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 :

Only the "Doc" mailbox if "Projects" & "IMAP" already exist.
"IMAP" & "Doc" mailboxes if only “Projects” already exists.
"Projects" & “IMAP” & "Doc" mailboxes, if they do not already exist.

In the name parameter, pass the name of the new mailbox.

Returned object

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

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

Exemple

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

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

$options:=New object

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

$transporter:=IMAP New transporter($options)

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

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

.delete()

Historique

Release	Modifications
18 R5	Ajout

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

Paramètres	Type		Description
msgsIDs	Collection	->	Collection d'IDs uniques de messages (texte)
allMsgs	Integer	->	`IMAP all`: All messages in the selected mailbox
Résultat	Object	<-	Statut de l'opération de suppression

Description

The .delete() function sets the "deleted" flag for the messages defined in msgsIDs or allMsgs.

Vous pouvez passer :

in the msgsIDs parameter, a collection containing the unique IDs of the specific messages to delete, or
in the allMsgs parameter, the IMAP all constant (integer) to delete all messages in the selected mailbox.

L'exécution de cette fonction ne supprime pas réellement les messages. Messages with the "delete" flag can still be found by the .searchMails() function. Flagged messages are deleted from the IMAP server with the .expunge() function or by selecting another mailbox or when the transporter object (created with IMAP New transporter) is destroyed.

Returned object

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

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

Exemple 1

Pour supprimer une sélection de messages :

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

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

 $transporter:=IMAP New transporter($server)

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

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

  // Delete selected messages
 $status:=$transporter.delete($mailIds)

Exemple 2

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

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

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

 $transporter:=IMAP New transporter($server)

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

  // delete all messages in the current mailbox
 $status:=$transporter.delete(IMAP all)

.deleteBox()

Historique

Release	Modifications
19	Ajout

.deleteBox( name : Text ) : Object

Paramètres	Type		Description
name	Text	->	Nom de la boîte de réception à supprimer
Résultat	Object	<-	Statut de l'opération de suppression de boîte

Description

The .deleteBox() function permanently removes the mailbox with the given name from the IMAP server. 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.

In the name parameter, pass the name of the mailbox to delete.

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.

Returned object

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

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

Exemple

Vous souhaitez supprimer la boîte enfant "Nova Orion Industries" à l'intérieur de la boîte "Bills" :

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

$options:=New object

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

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

$transporter:=IMAP New transporter($options)

// delete mailbox
$name:="Bills"+$transporter.getDelimiter()+"Nova Orion Industries"
$status:=$transporter.deleteBox($name)

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

.expunge()

Historique

Release	Modifications
18 R6	Ajout

.expunge() : Object

Paramètres	Type		Description
Résultat	Object	<-	Statut de l'opération expunge

Description

The .expunge() function removes all messages with the "deleted" flag from the IMAP mail server. The "deleted" flag can be set with the .delete() or .addFlags() methods.

Returned object

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

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

Exemple

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

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

// Creation du transporter
$transporter:=IMAP New transporter($options)

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

// Chercher et sélectionner les messages lus dans INBOX
$ids:=$transporter.searchMails("SEEN")
$status:=$transporter.delete($ids)

// Purger tous les messages marqués deleted
$status:=$transporter.expunge()

.getBoxInfo()

Historique

Release	Modifications
20	id is returned
18 R5	name is optional
18 R4	Ajout

.getBoxInfo( { name : Text }) : Object

Paramètres	Type		Description
name	Text	->	Nom de la boîte de réception
Résultat	Object	<-	Objet boxInfo

Description

The .getBoxInfo() function returns a boxInfo object corresponding to the current maibox, or the mailbox name. This function returns the same information as .selectBox() without changing the current mailbox.

In the optional name parameter, pass the name of the mailbox to access. 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. The delimiter can be found with the .getDelimiter() function.

If the mailbox name is not selectable or does not exist, the function generates an error and returns null.

Returned object

The boxInfo object returned contains the following properties:

Propriété	Type	Description
name	text	Nom de la boîte de réception
mailCount	number	Nombre de messages contenus dans la boîte de réception
mailRecent	number	Nombre de messages portant le marqueur "récent" (indiquant les nouveaux messages)
id	text	Identifiant unique de la boîte aux lettres

Exemple

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

 $info:=$transporter.getBoxInfo("INBOX")
 ALERT("INBOX contains "+String($info.mailRecent)+" recent emails.")

.getBoxList()

Historique

Release	Modifications
18 R4	Ajout
19	Add `isSubscribed` parameter

.getBoxList( { parameters : Object } ) : Collection

Paramètres	Type		Description
parameters	Object	->	Objet de paramètre
Résultat	Collection	<-	Collection d'objets mailbox

Description

The .getBoxList() function returns a collection of mailboxes describing all of the available mailboxes. Cette fonction vous permet de gérer localement les listes de messages situés sur le serveur de messagerie IMAP.

In the optional parameters parameter, pass an object containing values to filter the returned mailboxes. Vous pouvez passer :

Propriété	Type	Description
isSubscribed	Boolean	True to return only subscribed mailboxes False to return all available mailboxes

Résultat

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

Propriété	Type	Description
[].name	text	Nom de la boîte de réception
[].selectable	boolean	Indicates whether or not the access rights allow the mailbox to be selected: true - the mailbox can be selected false - the mailbox can not be selected
[].inferior	boolean	Indicates whether or not the access rights allow creating a lower hierachy in the mailbox: true - a lower level can be created false - a lower level can not be created
[].interesting	boolean	Indicates if the mailbox has been marked "interesting" by the server: true - The mailbox has been marked "interesting" by the server. For example, it may contain new messages. false - The mailbox has not been marked "interesting" by the server.

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

If there is no open connection, .getBoxList() will open a connection.
If the connection has not been used since the designated connection delay (see IMAP New transporter), the .checkConnection( ) function is automatically called.

Exemple

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

 $boxList:=$transporter.getBoxList()

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

.getDelimiter()

Historique

Release	Modifications
18 R4	Ajout

.getDelimiter() : Text

Paramètres	Type		Description
Résultat	Text	<-	Caractère de délimitation de hiérarchie

Description

The .getDelimiter() function returns the character used to delimit levels of hierarchy in the mailbox name.

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.

If there is no open connection, .getDelimiter() will open a connection.
If the connection has not been used since the designated connection delay, the .checkConnection() function is automatically called.

Exemple

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

 $boxList:=$transporter.getBoxList()

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

.getMail()

Historique

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
msgNumber	Integer	->	Numéro de séquence du message
msgID	Text	->	ID unique du message
options	Object	->	Instructions sur la gestion du message
Résultat	Object	<-	Email object

Description

The .getMail() function returns the Email object corresponding to the msgNumber or msgID in the mailbox designated by the 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, an integer value indicating the sequence number of the message to retrieve or
msgID, a text value indicating the unique ID of the message to retrieve.

The optional options parameter allows you pass an object defining additional instructions for handling the message. Les propriétés suivantes sont disponibles :

Propriété	Type	Description
updateSeen	boolean	Si Vrai, le message est marqué comme "seen" (lu) dans la boite de réception. Si Faux, le message n'est pas marqué comme "seen". Valeur par défaut : Vrai
withBody	boolean	Passez Vrai pour retourner le corps du message. Si Faux, seul l'en-tête du message est retourné. Valeur par défaut : Vrai

The function generates an error and returns Null if msgID designates a non-existing message,
If no mailbox is selected with the .selectBox() function, an error is generated,
If there is no open connection, .getMail() will open a connection the last mailbox specified with .selectBox()`.

Résultat

.getMail() returns an Email object with the following specific IMAP properties: id, receivedAt, and size.

Exemple

Vous souhaitez lire le message avec ID = 1 :

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

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

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

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

  //get Email object with ID 1
 $mail:=$transporter.getMail(1)

.getMails()

Historique

Release	Modifications
18 R5	Ajout

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

Paramètres	Type		Description
ids	Collection	->	Collection d'identifiants de messages
startMsg	Integer	->	Numéro de séquence du premier message
endMsg	Integer	->	Numéro de séquence du dernier message
options	Object	->	Instructions sur la gestion du message
Résultat	Object	<-	Object containing: a collection of Email objects and a collection of IDs or numbers for missing messages, if any

Description

The .getMails() function returns an object containing a collection of Email objects.

First Syntax:

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

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

In the ids parameter, pass a collection of IDs for the messages to return. You can get the IDs with .getMail().

The optional options parameter allows you to define the parts of the messages to be returned. See the Options table below for a description of the available properties.

Second syntax:

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

In the startMsg parameter, pass an integer value corresponding to the number of the first message in a sequential range. If you pass a negative number (startMsg <= 0), the first message of the mailbox will be used as the beginning of the sequence.

In the endMsg parameter, pass an integer value corresponding to the number of the last message to be included in a sequential range. If you pass a negative number (endMsg <= 0), the last message of the mailbox will be used as the end of the sequence.

The optional options parameter allows you to define the parts of the messages to be returned.

Options

Propriété	Type	Description
updateSeen	Boolean	Si Vrai, les messages sont marqués comme "seen" (lus) dans la boite de réception. Si Faux, les messages ne sont pas marqués comme "seen". Valeur par défaut : Vrai
withBody	Boolean	Passez Vrai pour retourner le corps des messages spécifiés. Si Faux, seuls les en-tête des messages sont retournés. Valeur par défaut : Vrai

If no mailbox is selected with the .selectBox() command, an error is generated.
If there is no open connection, .getMails() will open a connection the last mailbox specified with .selectBox().

Résultat

.getMails() returns an object containing the following collections:

Propriété	Type	Description
liste	Collection	Collection of `Email` objects. Si aucun objet Email n'est trouvé, une collection vide est retournée.
notFound	Collection	Collection of: first syntax - previously passed message IDs that do not exist second syntax - sequence numbers of messages between startMsg and endMsg that do not exist An empty collection is returned if all messages are found.

Exemple

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

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

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

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

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

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

.getMIMEAsBlob()

Historique

Release	Modifications
18 R4	Ajout

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

Paramètres	Type		Description
msgNumber	Integer	->	Numéro de séquence du message
msgID	Text	->	ID unique du message
updateSeen	Boolean	->	Si Vrai, le message est marqué comme "seen" (lu) dans la boite de réception. Si Faux, le message demeure inchangé.
Résultat	BLOB	<-	Blob de la chaine MIME retournée par le serveur mail

Description

The .getMIMEAsBlob() function returns a BLOB containing the MIME contents for the message corresponding to the msgNumber or msgID in the mailbox designated by the IMAP_transporter.

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

msgNumber, an integer value indicating the sequence number of the message to retrieve or
msgID, a text value indicating the unique ID of the message to retrieve.

The optional updateSeen parameter allows you to specify if the message is marked as "seen" in the mailbox. Vous pouvez passer :

True - to mark the message as "seen" (indicating the message has been read)
False - to leave the message's "seen" status untouched

The function returns an empty BLOB if msgNumber or msgID* designates a non-existing message,
If no mailbox is selected with the .selectBox() command, an error is generated,
If there is no open connection, .getMIMEAsBlob() will open a connection the last mailbox specified with .selectBox().

Résultat

.getMIMEAsBlob() returns a BLOB which can be archived in a database or converted to an Email object with the MAIL Convert from MIME command.

Exemple

 var $server : Object
 var $boxInfo : Variant
 var $blob : Blob
 var $transporter : 4D.IMAPTransporter

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

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

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

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

.host

Historique

Release	Modifications
17 R5	Ajout

.host : Text

Description

The .host property contains the name or the IP address of the host server. Utilisée pour les échanges de courrier (SMTP, POP3, IMAP).

.logFile

Historique

Release	Modifications
17 R5	Ajout

.logFile : Text

Description

The .logFile property contains the path of the extended log file defined (if any) for the mail connection. Le chemin peut être relatif (au dossier Logs courant) ou absolu.

Unlike regular log files (enabled via the SET DATABASE PARAMETER command), extended log files store MIME contents of all sent mails and do not have any size limit. Pour plus d'informations sur les fichiers log étendus, reportez-vous à :

SMTP connections - 4DSMTPLog.txt
POP3 connections - 4DPOP3Log.txt
IMAP connections - 4DIMAPLog.txt

.move()

Historique

Release	Modifications
18 R5	Ajout

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

Paramètres	Type		Description
msgsIDs	Collection	->	Collection d'IDs uniques de messages (texte)
allMsgs	Integer	->	`IMAP all`: All messages in the selected mailbox
destinationBox	Text	->	Boîte de réception recevant les messages déplacés
Résultat	Object	<-	Statut de l'opération de déplacement

Description

The .move() function moves the messages defined by msgsIDs or allMsgs to the destinationBox on the IMAP server.

Vous pouvez passer :

in the msgsIDs parameter, a collection containing the unique IDs of the specific messages to move, or
in the allMsgs parameter, the IMAP all constant (integer) to move all messages in the selected mailbox.

The destinationBox parameter allows you to pass a text value with the name of the mailbox where the messages will be moved.

This function is only supported by IMAP servers compliant with RFC 8474.

Returned object

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

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

Exemple 1

Pour déplacer une sélection de messages :

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

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

 $transporter:=IMAP New transporter($server)

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

  //get collection of message unique IDs
 $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")

  // Move found messages from the current mailbox to the "documents" mailbox
 $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)

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

  // move all messages in the current mailbox to the "documents" mailbox
 $status:=$transporter.move(IMAP all;"documents")

.numToID()

Historique

Release	Modifications
18 R5	Ajout

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

Paramètres	Type		Description
startMsg	Integer	->	Numéro de séquence du premier message
endMsg	Integer	->	Numéro de séquence du dernier message
Résultat	Collection	<-	Collection d'identifiants de messages uniques

Description

The .numToID() function converts the sequence numbers to IMAP unique IDs for the messages in the sequential range designated by startMsg and endMsg in the currently selected mailbox.

In the startMsg parameter, pass an integer value corresponding to the number of the first message in a sequential range. If you pass a negative number (startMsg <= 0), the first message of the mailbox will be used as the beginning of the sequence.

In the endMsg parameter, pass an integer value corresponding to the number of the last message to be included in a sequential range. If you pass a negative number (endMsg <= 0), the last message of the mailbox will be used as the end of the sequence.

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)

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

  //get IDs for 5 last messages received
 $mailIds:=$transporter.numToID(($boxInfo.mailCount-5);$boxInfo.mailCount)

  //delete the messages from the current mailbox
 $status:=$transporter.delete($mailIds)

.removeFlags()

Historique

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

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

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

Description

The .removeFlags() function removes flags from the msgIDs for the specified keywords.

In the msgIDs parameter, you can pass either:

a collection containing the unique IDs of specific messages or
the unique ID (text) of a single message or
the following constant (longint) for all messages in the selected mailbox:

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

The keywords parameter lets you define the flags to remove from msgIDs. Vous pouvez utiliser les flags standard suivants ainsi que des flags personnalisés :

Paramètres	Type	Description
$draft	Boolean	True pour supprimer le marqueur "draft" du message
$seen	Boolean	True pour supprimer le marqueur "seen" du message
$flagged	Boolean	True pour supprimer le marqueur "flagged" du message
$answered	Boolean	True pour supprimer le marqueur "answered" du message
$deleted	Boolean	True pour supprimer le marqueur "deleted" du message
`<custom flag>`	Boolean	True pour supprimer le flag personnalisé du message

Please refer to .addFlags() for more information on custom flags.

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

Returned object

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

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

Exemple

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

$options:=New object

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

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

$transporter:=IMAP New transporter($options)

// renommer la boite de réception
$status:=$transporter.renameBox("Invoices"; "Bills")

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

.renameBox()

Historique

Release	Modifications
19	Ajout

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

Paramètres	Type		Description
currentName	Text	->	Nom actuel de la boîte de réception
nouveauNom	Text	->	Nom de la nouvelle mailbox
Résultat	Object	<-	Statut de l'opération renaming

Description

The .renameBox() function changes the name of a mailbox on the IMAP server. 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.

In the currentName parameter, pass the name of the mailbox to be renamed.

Pass the new name for the mailbox in the newName parameter.

Returned object

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

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

Exemple

Pour renommer la mailbox “Invoices” en “Bills”:

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

$options:=New object

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

If(OK=1) $options.host:="imap.gmail.com"

$options.user:="test@gmail.com"
$options.password:=$pw

$transporter:=IMAP New transporter($options)

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

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

.port

Historique

Release	Modifications
17 R4	Ajout

.port : Integer

Description

The .port property contains the port number used for mail transactions. By default, if the port property has not been set in the server object (used to create the transporter object with SMTP New transporter, POP3 New transporter, IMAP New transporter), the port used is:

SMTP - 587
POP3 - 995
IMAP - 993

.searchMails()

Historique

Release	Modifications
18 R5	Ajout

.searchMails( searchCriteria : Text ) : Collection

Paramètres	Type		Description
searchCriteria	Text	->	Critère(s) de recherche
Résultat	Collection	<-	Collection de numéros de messages

Description

This function is based upon the specification for the IMAP protocol.

The .searchMails() function searches for messages that match the given searchCriteria in the current mailbox. searchCriteria consists of one or more search keys.

searchCriteria is a text parameter listing one or more search keys (see Authorized search-keys below) associated or not with values to look for. 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

If the searchCriteria is a null string, the search will be equivalent to a “select all”.
If the searchCriteria includes multiple search keys, the result is the intersection (AND function) of all the messages that match those keys.

searchCriteria = FLAGGED FROM "SMITH"

... returns all messages with \Flagged flag set AND sent by Smith.

You can use the OR or NOT operators as follows:

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.

The searchCriteria may include the optional [CHARSET] specification. Cette instruction est composée du mot "CHARSET" suivi d'un jeu de caractères défini [CHARSET] (US ASCII, ISO-8859). It indicates the charset of the searchCriteria string. Therefore, you must convert the searchCriteria string into the specified charset if you use the [CHARSET] specification (see the CONVERT FROM TEXT or Convert to text commands). 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"

... means the search criteria uses the charset iso-8859 and the server will have to convert the search criteria before searching, if necessary.

Mots-clés de recherche autorisés

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

Search-keys with a date value: the date is a string that must be formatted as follows: date-day+"-"+date-month+"-"+date-year where date-day indicates the number of the day of the month (max. 2 characters), date-month indicates the name of the month (Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Dec) and date-year indicates the year (4 characters). Example: searchCriteria = SENTBEFORE 1-Feb-2020 (a date does not usually need to be quoted since it does not contain any special characters)
Search-keys with a string value: the string may contain any character and must be quoted. 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.
Search-keys with a field-name value: the field-name is the name of a header field. Example: searchCriteria = HEADER CONTENT-TYPE "MIXED"
Search-keys with a flag value: the flag may accept one or several keywords (including standard flags), separated by spaces. Example: searchCriteria = KEYWORD \Flagged \Draft
Search-keys with a message set value: Identifies a set of 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 search in message selection from message sequence number 1 to 5 for messages which have the \Answered flag set. searchCriteria= 2,4 ANSWERED search in the message selection (message numbers 2 and 4) for messages which have the \Answered flag set.

Mots-clés de recherche autorisés

ALL: All messages in the mailbox.\ ANSWERED: Messages with the \Answered flag set.\ UNANSWERED: Messages that do not have the \Answered flag set.\ DELETED: Messages with the \Deleted flag set.\ UNDELETED: Messages that do not have the \Deleted flag set.\ DRAFT: Messages with the \Draft flag set.\ UNDRAFT: Messages that do not have the \Draft flag set.\ FLAGGED: Messages with the \Flagged flag set.\ UNFLAGGED: Messages that do not have the \Flagged flag set.\ RECENT: Messages that have the \Recent flag set.\ OLD: Messages that do not have the \Recent flag set.\ SEEN: Messages that have the \Seen flag set.\ UNSEEN: Messages that do not have the \Seen flag set.\ NEW: Messages that have the \Recent flag set but not the \Seen flag. Equivaut à “(RECENT UNSEEN)”.\ KEYWORD flag: Messages with the specified keyword set.\ UNKEYWORD flag: Messages that do not have the specified keyword set.\ BEFORE date: Messages whose internal date is earlier than the specified date.\ ON date: Messages whose internal date is within the specified date.\ SINCE date: Messages whose internal date is within or later than the specified date.\ SENTBEFORE date: Messages whose Date header is earlier than the specified date.\ SENTON date: Messages whose Date header is within the specified date.\ SENTSINCE date: Messages whose Date header is within or later than the specified date.\ TO string: Messages that contain the specified string in the TO header.\ FROM string: Messages that contain the specified string in the FROM header.\ CC string: Messages that contain the specified string in the CC header.\ BCC string: Messages that contain the specified string in the BCC header.\ SUBJECT string: Messages that contain the specified string in the Subject header.\ BODY string: Messages that contain the specified string in the message body.\ TEXT string: Messages that contain the specified string in the header or in the message body.\ HEADER field-name string: Messages that have a header with the specified field-name and that contain the specified string in the field-body.\ UID message-UID: Messages with unique identifiers corresponding to the specified unique identifier set.\ LARGER n: Messages with a size larger than the specified number of bytes.\ SMALLER n: Messages with a size smaller than the specified number of bytes.\ NOT search-key: Messages that do not match the specified search key.\ OR search-key1 search-key2: Messages that match either search key.

.selectBox()

Historique

Release	Modifications
20	id, flags, permanentFlags are returned
18 R4	Ajout

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

Paramètres	Type		Description
name	Text	->	Nom de la boîte de réception
state	Integer	->	Statut de l'accès à la boite de réception
Résultat	Object	<-	Objet boxInfo

Description

The .selectBox() function selects the name mailbox as the current mailbox. Cette fonction vous permet de récupérer des informations sur la boite de réception.

To get the information from a mailbox without changing the current mailbox, use .getBoxInfo().

In the name parameter, pass the name of the mailbox to access. 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. The delimiter can be found with the .getDelimiter() function.

The optional state parameter defines the type of access to the mailbox. Les valeurs possibles sont les suivantes :

Constante	Valeur	Commentaire
IMAP read only state	1	La mailbox sélectionnée est accessible avec les privilèges de lecture seule. Les messages contenant un marqueur "recent" (indication de nouveaux messages) restent inchangés.
IMAP read write state	0	La mailbox sélectionnée est accessible avec des privilèges de lecture et d'écriture. Les messages sont considérés "seen" et perdent le marqueur "recent" (indication des nouveaux messages). (Valeur par défaut)

The function generates an error and returns Null if name designates a non-existing mailbox.
If there is no open connection, .selectBox() will open a connection.
If the connection has not been used since the designated connection delay (see IMAP New transporter), the .checkConnection() function is automatically called.

Returned object

The boxInfo object returned contains the following properties:

Propriété	Type	Description
name	Text	Nom de la boîte de réception
mailCount	number	Nombre de messages contenus dans la boîte de réception
mailRecent	number	Nombre de messages avec le marqueur "recent"
id	text	Identifiant unique de la boîte aux lettres
flags	text	Liste des flags actuellement utilisés pour la boîte aux lettres, séparés par des espaces
permanentFlags	text	Liste des flags que le client peut modifier en permanence (à l'exception de l'indicateur \Recent, qui est géré par le serveur IMAP), séparés par des espaces

info

If permanentFlags string includes the special flag *, it means that the server supports custom flags.

Exemple

 var $server; $boxinfo : Object
 $server:=New object
 $server.host:="imap.gmail.com" //Obligatoire
 $server.user:="4d@gmail.com"
 $server.password:="XXXXXXXX"

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

Historique

Release	Modifications
19	Ajout

.subscribe( name : Text ) : Object

Paramètres	Type		Description
name	Text	->	Nom de la boîte de réception
Résultat	Object	<-	Statut de l'opération subscribe

Description

The .subscribe() function allows adding or removing of the specified mailbox to/from the IMAP server’s set of “subscribed” mailboxes. 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.

In the name parameter, pass the name of the mailbox to add (subscribe) to your "subscribed" mailboxes.

Returned object

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

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

Exemple

Pour souscrire à la mailbox "Atlas Corp” dans la hiérarchie "Bills" :

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

$options:=New object

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

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

$transporter:=IMAP New transporter($options)

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

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

.unsubscribe()

Historique

Release	Modifications
19	Ajout

.unsubscribe( name : Text ) : Object

Paramètres	Type		Description
name	Text	->	Nom de la boîte de réception
Résultat	Object	<-	Statut de l'opération unsubscribe

Description

The .unsubscribe() function removes a mailbox from a set of subscribed mailboxes. Elle vous permet de réduire le nombre de mailboxes que vous consultez régulièrement.

In the name parameter, pass the name of the mailbox to remove (unsubscribe) from your active mailboxes.

Returned object

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

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

Exemple

Pour ne plus souscrire à la mailbox "Atlas Corp” dans la hiérarchie "Bills" :

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

$options:=New object

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

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

$transporter:=IMAP New transporter($options)

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

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

.user

Historique

Release	Modifications
17 R4	Ajout

.user : Text

Description

The .user property contains the user name used for authentication on the mail server.

Objet IMAP Transporter​

IMAP New transporter​

Description​

Résultat​

Exemple​

4D.IMAPTransporter.new()​

Description​

.acceptUnsecureConnection​

Description​

.addFlags()​

Description​

Exemple​

.append()​

Description​

Exemple​

.authenticationMode​

Description​

.checkConnection()​

Description​

Objet retourné​

.checkConnectionDelay​

Description​

.connectionTimeOut​

Description​

.copy()​

Description​

Exemple 1​

Exemple 2​

.createBox()​

Description​

Exemple​

.delete()​

Description​

Exemple 1​

Exemple 2​

.deleteBox()​

Description​

Exemple​

.expunge()​

Description​

Exemple​

.getBoxInfo()​

Description​

Exemple​

.getBoxList()​

Description​

Résultat​

Exemple​

.getDelimiter()​

Description​

Résultat​

Exemple​

.getMail()​

Description​

Résultat​

Exemple​

.getMails()​

Description​

Résultat​

Exemple​

.getMIMEAsBlob()​

Description​

Résultat​

Exemple​

.host​

Description​

.logFile​

Description​

.move()​

Description​

Exemple 1​

Exemple 2​

.numToID()​

Description​

Résultat​

Exemple​

.removeFlags()​

Description​

Exemple​

.renameBox()​

Objet IMAP Transporter

IMAP New transporter

Description

Résultat

Exemple

4D.IMAPTransporter.new()

Description

.acceptUnsecureConnection

Description

.addFlags()

Description

Exemple

.append()

Description

Exemple

.authenticationMode

Description

.checkConnection()

Description

Objet retourné

.checkConnectionDelay

Description

.connectionTimeOut

Description

.copy()

Description

Exemple 1

Exemple 2

.createBox()

Description

Exemple

.delete()

Description

Exemple 1

Exemple 2

.deleteBox()

Description

Exemple

.expunge()

Description

Exemple

.getBoxInfo()

Description

Exemple

.getBoxList()

Description

Résultat

Exemple

.getDelimiter()

Description

Résultat

Exemple

.getMail()

Description

Résultat

Exemple

.getMails()

Description

Résultat

Exemple

.getMIMEAsBlob()

Description

Résultat

Exemple

.host

Description

.logFile

Description

.move()

Description

Exemple 1

Exemple 2

.numToID()

Description

Résultat

Exemple

.removeFlags()

Description

Exemple

.renameBox()