Skip to main content

POP3Transporter

The POP3Transporter class allows you to retrieve messages from a POP3 email server.

Functions and properties​

POP3 Transporter objects provide the following properties and functions:

4D.POP3Transporter.new( server : object ) : 4D.POP3Transporter
configures a new POP3 connection
.acceptUnsecureConnection : boolean
true if Qodly is allowed to establish an unencrypted connection
.authenticationMode : string
the authentication mode used to open the session on the mail server
.checkConnection() : object
checks the connection using information stored in the transporter object
.connectionTimeOut : integer
the maximum wait time (in seconds) allowed to establish a connection to the server
.delete( msgNumber : integer )
flags the msgNumber email for deletion from the POP3 server
.getBoxInfo() : object
returns a boxInfo object corresponding to the mailbox designated by the POP3 transporter object
.getMail( msgNumber : integer { ; headerOnly : boolean } ) : object
returns the Email object corresponding to the msgNumber in the mailbox designated by the POP3 transporter
.getMailInfo( msgNumber : integer ) : object
returns a mailInfo object corresponding corresponding to the msgNumber in the mailbox designated by the POP3 transporter
.getMailInfoList() : collection
returns a collection of mailInfo objects describing all messages in the mailbox designated by the POP3 transporter
.getMIMEAsBlob( msgNumber : integer ) : Blob
returns a BLOB containing the MIME contents for the message corresponding to the msgNumber in the mailbox designated by the POP3_transporter
.host : string
the name or the IP address of the host server
.logFile : string
the path of the extended log file defined (if any) for the mail connection
.port : integer
the port number used for mail transactions
.undeleteAll()
removes all delete flags set on the emails in the POP3_transporter object
.user : string
the user name used for authentication on the mail server

4D.POP3Transporter.new()​

4D.POP3Transporter.new( server : object ) : 4D.POP3Transporter

ParameterTypeDescription
serverobject->Mail server information
Result4D.POP3Transporter<-POP3 transporter object

Description​

The 4D.POP3Transporter.new() function configures a new POP3 connectionaccording to the server parameter and returns a new POP3 transporter object. The returned transporter object will then usually be used to receive emails.

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

serverDefault value (if omitted)
.acceptUnsecureConnection : boolean
true if Qodly is allowed to establish an unencrypted connection		false
.accessTokenOAuth2: string
.accessTokenOAuth2: object
string 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 SMTP transporter object.		none
.authenticationMode : string
the authentication mode used to open the session on the mail server		the most secure authentication mode supported by the server is used
.connectionTimeOut : integer
the maximum wait time (in seconds) allowed to establish a connection to the server		30
.host : string
the name or the IP address of the host server		mandatory
.logFile : string
the path of the extended log file defined (if any) for the mail connection		none
.password : string
User password for authentication on the server. Not returned in SMTP transporter object.		none
.port : integer
the port number used for mail transactions		995
.user : string
the user name used for authentication on the mail server		none

Result​

The function returns a POP3 transporter object. All returned properties are read-only.

note

The POP3 connection is automatically closed when the transporter object is destroyed.

Example​

var server : object
var transporter : 4D.POP3Transporter
var status : object
var info : string


server = newObject()
server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password = "XXXXXXXX"
server.logFile = "LogTest.txt" //log to save in the Logs folder

transporter = 4D.POP3Transporter.new(server)

status = transporter.checkConnection()
if(not(status.success))
  info = "An error occurred receiving the mail: "+status.statusText)
end

.acceptUnsecureConnection​

.acceptUnsecureConnection : boolean

Description​

The .acceptUnsecureConnection property contains true if Qodly 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.

Available secured ports are:

  • SMTP

    • 465: SMTPS
    • 587 or 25: SMTP with STARTTLS upgrade if supported by the server.

  • IMAP

    • 143: IMAP non-encrypted port
    • 993: IMAP with STARTTLS upgrade if supported by the server

  • POP3

    • 110: POP3 non-encrypted port
    • 995: POP3 with STARTTLS upgrade if supported by the server.

.authenticationMode​

.authenticationMode : string

Description​

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

By default, the most secured mode supported by the server is used.

Possible values are:

ValueConstantsComment
APOPkPOP3AuthenticationAPOPAuthentication using APOP protocol (POP3 only)
CRAM-MD5kPOP3AuthenticationCRAMMD5Authentication using CRAM-MD5 protocol
LOGINkPOP3AuthenticationLoginAuthentication using LOGIN protocol
OAUTH2kPOP3AuthenticationOAUTH2Authentication using OAuth2 protocol
PLAINkPOP3AuthenticationPlainAuthentication using PLAIN protocol

.checkConnection()​

.checkConnection() : object

ParameterTypeDescription
Resultobject<-Status of the transporter object connection

Description​

The .checkConnection() function checks the connection using information stored in the transporter object, recreates the connection if necessary, and returns the status. This function allows you to verify that the values provided by the user are valid and consistent.

Returned object​

The function sends a request to the mail server and returns an object describing the mail status. This object can contain the following properties:

PropertyTypeDescription
successbooleantrue if the check is successful, false otherwise
statusnumber(SMTP only) Status code returned by the mail server (0 in case of an issue unrelated to the mail processing)
statusTexttextStatus message returned by the mail server, or last error returned in the Qodly error stack
errorscollectionQodly error stack (not returned if a mail server response is received)
[ ].errCodenumberQodly error code
[ ].messagetextDescription of the Qodly error
[ ].componentSignaturetextSignature of the internal component which returned the error

Example​

var options : object
var transporter : 4D.POP3Transporter
var status : object
var info : string

options = newObject()

options.host = "pop3.gmail.com"
options.user = "test@gmail.com"
options.password = "XXXXXXXX"

transporter = 4D.POP3Transporter.new(options)

status = transporter.checkConnection()
if(status.success)
  info = "POP3 connection check successful!"
else
  info = "Error: "+status.statusText
end

.connectionTimeOut​

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

.delete()​

.delete( msgNumber : integer )

ParameterTypeDescription
msgNumberinteger->Number of the message to delete
Description​

The .delete() function flags the msgNumber email for deletion from the POP3 server.

In the msgNumber parameter, pass the number of the email to delete. This number is returned in the number property by the .getMailInfoList() function.

Executing this function does not actually remove any email. The flagged email will be deleted from the POP3 server only when the POP3_transporter object is destroyed. The flag could be also be removed using the .undeleteAll() function.

note

If the current session unexpectedly terminates and the connection is closed (e.g., timeout, network failure, etc.), an error message is generated and messages marked for deletion will remain on the POP3 server.

Example​
var mailInfoList : collection
var mailInfo : object
var confirmed : boolean

mailInfoList = POP3_transporter.getMailInfoList()
forEach (mailInfo , mailInfoList)
  // Mark your mail as "to be deleted at the end of the session"
  POP3_transporter.delete(mailInfo.number)
end
  // Force the session closure to delete the mails marked for deletion

if(confirmed) //deletion is confirmed by a user
  POP3_transporter = null
else
  POP3_transporter.undeleteAll() //remove deletion flags
end

.getBoxInfo()​

.getBoxInfo() : object

ParameterTypeDescription
Resultobject<-boxInfo object
Description​

The .getBoxInfo() function returns a boxInfo object corresponding to the mailbox designated by the POP3 transporter object. This function allows you to retrieve information about the mailbox.

The boxInfo object returned contains the following properties:

PropertyTypeDescription
mailCountnumberNumber of messages in the mailbox
sizenumberMessage size in bytes
Example​
var server , boxinfo : object
var transporter : 4D.POP3Transporter
var info : string


server = newObject()
server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password = "XXXXXXXX"

transporter = 4D.POP3Transporter.new(server)

  //mailbox info
boxInfo = transporter.getBoxInfo()
info = "The mailbox contains "+string(boxInfo.mailCount)+" messages.")

.getMail()​

.getMail( msgNumber : integer { ; headerOnly : boolean } ) : object

ParameterTypeDescription
msgNumberinteger->Number of the message in the list
headerOnlyboolean->True to download only the email headers (default is false)
Resultobject<-Email object
Description​

The .getMail() function returns the Email object corresponding to the msgNumber in the mailbox designated by the POP3 transporter. This function allows you to locally handle the email contents.

Pass in msgNumber the number of the message to retrieve. This number is returned in the number property by the .getMailInfoList() function.

Optionally, you can pass true in the headerOnly parameter to exclude the body parts from the returned Email object. Only headers properties (headers, to, from...) are then returned. This option allows you to optimize the downloading step when a lot of emails are on the server.

note

The headerOnly option may not be supported by the server.

The function returns Null if:

  • msgNumber designates a non-existing message,
  • the message was marked for deletion using .delete().

Returned object

.getMail() returns an Email object.

Example​

You want to know the sender of the first mail of the mailbox:

var server : object
var transporter : 4D.POP3Transporter
var mailInfo : collection
var sender : variant

server = newObject()
server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password = "XXXXXXXX"

transporter = 4D.POP3Transporter.new (server)

mailInfo = transporter.getMailInfoList()

sender = transporter.getMail(mailInfo[0].number).from

.getMailInfo()​

.getMailInfo( msgNumber : integer ) : object

ParameterTypeDescription
msgNumberinteger->Number of the message in the list
Resultobject<-mailInfo object
Description​

The .getMailInfo() function returns a mailInfo object corresponding corresponding to the msgNumber in the mailbox designated by the POP3 transporter. This function allows you to retrieve information about the email.

In msgNumber, pass the number of the message to retrieve. This number is returned in the "number" property by the .getMailInfoList() function.

The mailInfo object returned contains the following properties:

PropertyTypeDescription
sizenumberMessage size in bytes
idstringUnique ID of the message

The method returns Null if:

  • msgNumber designates a non-existing message,
  • the message was marked for deletion using .delete().
Example​
var server , mailInfo : object
var mailNumber : integer
var transporter : 4D.POP3Transporter
var info : string

server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password:="XXXXXXXX"

transporter = 4D.POP3Transporter.new (server)

 //message info
mailInfo = transporter.getMailInfo(1) //get the first mail
if (mailInfo != null)
   info = "First mail size is:"+string(mailInfo.size)+" bytes."
end

.getMailInfoList()​

.getMailInfoList() : collection

ParameterTypeDescription
Resultcollection<-Collection of mailInfo objects
Description​

The .getMailInfoList() function returns a collection of mailInfo objects describing all messages in the mailbox designated by the POP3 transporter. This function allows you to locally manage the list of messages located on the POP3 mail server.

Each mailInfo object in the returned collection contains the following properties:

PropertyTypeDescription
[].sizenumberMessage size in bytes
[].numbernumberMessage number
[].idstringUnique ID of the message (useful if you store the message locally)

If the mailbox does not contain a message, an empty collection is returned.

number and ID properties​

number is the number of a message in the mailbox at the time the POP3_transporter was created. The number property is not a static value in relation to any specific message and will change from session to session dependent on its relation to other messages in the mailbox at the time the session was opened. The numbers assigned to the messages are only valid during the lifetime of the POP3_transporter object. At the time the POP3_transporter is deleted any message marked for deletion will be removed. When the user logs back into the server, the current messages in the mailbox will be renumbered from 1 to x.

The id however is a unique number assigned to the message when it was received by the server. This number is calculated using the time and date that the message is received and is a value assigned by your POP3 server. Unfortunately, POP3 servers do not use the id as the primary reference to their messages. Throughout the POP3 sessions you will need to specify the number as the reference to messages on the server. Developers may need to take some care if developing solutions which bring references to messages into a database but leave the body of the message on the server.

Example​

You want to know the total number and size of emails in the mailbox:

var server : object
var transporter : 4D.POP3Transporter
var mailInfo : collection
var vNum , vSize : integer
var info = string

server = newObject()
server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password = "XXXXXXXX"

transporter = 4D.POP3Transporter.new (server)

mailInfo = transporter.getMailInfoList()
vNum = mailInfo.length
vSize = mailInfo.sum("size")

info = "The mailbox contains "+string(vNum)+" message(s) for "+string(vSize)+" bytes.")

.getMIMEAsBlob()​

.getMIMEAsBlob( msgNumber : integer ) : Blob

ParameterTypeDescription
msgNumberinteger->Number of the message in the list
Resultblob<-Blob of the MIME string returned from the mail server
Description​

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

In msgNumber, pass the number of the message to retrieve. This number is returned in the "number" property by the .getMailInfoList() function.

The function returns an empty BLOB if:

  • msgNumber designates a non-existing message,
  • the message was marked for deletion using .delete().

Returned blob

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

Example​

You want to know the total number and size of emails in the mailbox:

var server : object
var mailInfo : collection
var blob : blob
var transporter : 4D.POP3Transporter

server = newObject()
server.host = "pop.gmail.com" //Mandatory
server.port = 995
server.user = "qodly@gmail.com"
server.password = "XXXXXXXX"

transporter = 4D.POP3Transporter.new (server)

mailInfo = transporter.getMailInfoList()
blob = transporter.getMIMEAsBlob(mailInfo[0].number)

.host​

.host : string

Description​

The .host property contains the name or the IP address of the host server. Used for mail transactions (SMTP, POP3, IMAP).

.logFile​

.logFile : string

Description​

The .logFile property contains the path of the extended log file defined (if any) for the mail connection.

.port​

.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), the port used is:

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

.undeleteAll()​

.undeleteAll()

ParameterTypeDescription
Does not require any parameters
Description​

The .undeleteAll() function removes all delete flags set on the emails in the POP3_transporter object.

.user​

.user : string

Description​

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