POP3Transporter
The POP3Transporter
class allows you to retrieve messages from a POP3 email server.
POP3 Transporter object
POP3 Transporter objects are instantiated with the POP3 New transporter command. They provide the following properties and functions:
.acceptUnsecureConnection : Boolean True if 4D is allowed to establish an unencrypted connection |
.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 |
.connectionTimeOut : Integer the maximum wait time (in seconds) allowed to establish a connection to the server |
.delete( msgNumber : Integer ) marca o email msgNumber para ser apagado do servidor POP3 |
.getBoxInfo() : Object retorna um objeto |
.getMail( msgNumber : Integer ) : Object retorna o objeto |
.getMailInfo( msgNumber : Integer ) : Object
|
.getMailInfoList() : Collection retorna uma coleção de objetos |
.getMIMEAsBlob( msgNumber : Integer ) : Blob retorna uma BLOB contendo os conteúdos MIME para a mensagem correspondente a msgNumber na mailbox determinada pelo |
.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 |
.port : Integer the port number used for mail transactions |
.undeleteAll() remove todas as marcações para apagar nos emails no |
.user : Text the user name used for authentication on the mail server |
POP3 New transporter
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
POP3 New transporter( server : Object ) : 4D.POP3Transporter
Parameter | Type | Descrição | |
---|---|---|---|
server | object | -> | Mail server information |
Resultado | 4D.POP3Transporter | <- | Objeto POP3 transporter |
Descrição
O comando POP3 New transporter
configura uma nova conexão POP3de acordo com o parâmetro server e retorna um novo objetoPOP3 transporter. The returned transporter object will then usually be used to receive emails.
In the server parameter, pass an object containing the following properties:
server | Default value (if omitted) |
---|---|
.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 | nenhum |
.authenticationMode : Text 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 : Text the name or the IP address of the host server | mandatory |
.logFile : Text the path of the extended log file defined (if any) for the mail connection | nenhum |
.password : Text User password for authentication on the server. Not returned in SMTP transporter object. | nenhum |
.port : Integer the port number used for mail transactions | 995 |
.user : Text the user name used for authentication on the mail server | nenhum |
Resultado
A função retorna um objeto POP3 transporter. All returned properties are read-only.
The POP3 connection is automatically closed when the transporter object is destroyed.
Exemplo
var $server : Object
$server:=New object
$server.host:="pop.gmail.com" //Mandatory
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$server.logFile:="LogTest.txt" //log to save in the Logs folder
var $transporter : 4D.POP3Transporter
$transporter:=POP3 New transporter($server)
$status:=$transporter.checkConnection()
If(Not($status.success))
ALERT("An error occurred receiving the mail: "+$status.statusText)
End if
4D.POP3Transporter.new()
4D.POP3Transporter.new( server : Object ) : 4D.POP3Transporter
Parameter | Type | Descrição | |
---|---|---|---|
server | Objeto | -> | Mail server information |
Resultado | 4D.POP3Transporter | <- | Objeto POP3 transporter |
Descrição
A função 4D.POP3Transporter.new()
cria e retorna um novo objeto do tipo 4D.POP3Transporter
. Isso é idêntico ao comando (atalho) POP3 New transporter
.
.acceptUnsecureConnection
Histórico
Versão | Mudanças |
---|---|
v17 R4 | Adicionado |
.acceptUnsecureConnection : Boolean
Descrição
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.
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
Histórico
Versão | Mudanças |
---|---|
v17 R4 | Adicionado |
.authenticationMode : Text
Descrição
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:
Value | Constantes | Comment |
---|---|---|
APOP | POP3 authentication APOP | Authentication using APOP protocol (POP3 only) |
CRAM-MD5 | POP3 authentication CRAM-MD5 | Authentication using CRAM-MD5 protocol |
LOGIN | POP3 authentication login | Authentication using LOGIN protocol |
OAUTH2 | POP3 authentication OAUTH2 | Authentication using OAuth2 protocol |
PLAIN | POP3 authentication plain | Authentication using PLAIN protocol |
.checkConnection()
Histórico
Versão | Mudanças |
---|---|
v17 R4 | Adicionado |
.checkConnection() : Object
Parameter | Type | Descrição | |
---|---|---|---|
Resultado | Objeto | <- | Status of the transporter object connection |
Descrição
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:
Propriedade | Type | Descrição | |
---|---|---|---|
success | booleano | True if the check is successful, False otherwise | |
status | number | (SMTP only) Status code returned by the mail server (0 in case of an issue unrelated to the mail processing) | |
statusText | texto | Status message returned by the mail server, or last error returned in the 4D error stack | |
errors | collection | 4D error stack (not returned if a mail server response is received) | |
[ ].errCode | number | 4D error code | |
[ ].message | texto | Description of the 4D error | |
[ ].componentSignature | texto | Signature of the internal component which returned the error |
Exemplo
var $pw : Text
var $options : Object
$options:=New object
$pw:=Request("Please enter your password:")
if(OK=1)
$options.host:="pop3.gmail.com"
$options.user:="test@gmail.com"
$options.password:=$pw
$transporter:=POP3 New transporter($options)
$status:=$transporter.checkConnection()
If($status.success)
ALERT("POP3 connection check successful!")
Else
ALERT("Error: "+$status.statusText)
End if
End if
.connectionTimeOut
Histórico
Versão | Mudanças |
---|---|
v17 R5 | Adicionado |
.connectionTimeOut : Integer
Descrição
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()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.delete( msgNumber : Integer )
Parameter | Type | Descrição | |
---|---|---|---|
msgNumber | Integer | -> | Número da mensagem que vai ser apagada |
Descrição
A função .delete( )
function marca o email msgNumber para ser apagado do servidor POP3.
No parâmetro msgNumber, passe o número do email a apagar. O número é retornado na propriedade número pelo método .getMailInfoList()
.
Executar esse método não remove de verdade qualquer email. O email marcado será apagado do servidor POP3 apenas quando o objetoPOP3_transporter
(criado com POP3 New transporter
) for destruído. A marcação pode ser removida com o método .undeleteAll()
.
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.
Exemplo
$mailInfoList:=$POP3_transporter.getMailInfoList()
For each($mailInfo;$mailInfoList)
// Mark your mail as "to be deleted at the end of the session"
$POP3_transporter.delete($mailInfo.number)
End for each
// Force the session closure to delete the mails marked for deletion
CONFIRM("Selected messages will be deleted.";"Delete";"Undo")
If(OK=1) //deletion confirmed
$POP3_transporter:=Null
Else
$POP3_transporter.undeleteAll() //remove deletion flags
End if
.getBoxInfo()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.getBoxInfo() : Object
Parameter | Type | Descrição | |
---|---|---|---|
Resultado | Objeto | <- | boxInfo object |
Descrição
A função .getBoxInfo()
retorna um objeto boxInfo
correspondente ao mailbox determinado pelo POP3 transporter
. Essa função permite que recupere informação sobre o mailbox.
O objeto boxInfo
retornado contém as funcionalidades abaixo:
Propriedade | Type | Descrição |
---|---|---|
mailCount | Número | Number of messages in the mailbox |
size | Número | Tamanho da mensagem em bytes |
Exemplo
var $server; $boxinfo : Object
$server:=New object
$server.host:="pop.gmail.com" //Mandatory
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$transporter:=POP3 New transporter($server)
//mailbox info
$boxInfo:=$transporter.getBoxInfo()
ALERT("The mailbox contains "+String($boxInfo.mailCount)+" messages.")
.getMail()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.getMail( msgNumber : Integer ) : Object
Parameter | Type | Descrição | |
---|---|---|---|
msgNumber | Integer | -> | Número da mensagem que na lista |
Resultado | Objeto | <- | Email object |
Descrição
A função .getMail()
retorna o objetoEmail
correspondente a msgNumber na mailbox determinada pelo POP3 transporter
. Essa função permite manejar localmente os conteúdos de email.
Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pela função .getMailInfoList()
.
O método retorna Null se:
- msgNumber designates a non-existing message,
- the message was marked for deletion using
.delete( )
.
Returned object
.getMail()
returns an Email
object.
Exemplo
Se quiser saber o emissário do primeiro email da mailbox:
var $server; $transporter : Object
var $mailInfo : Collection
var $sender : Variant
$server:=New object
$server.host:="pop.gmail.com" //Mandatory
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$transporter:=POP3 New transporter($server)
$mailInfo:=$transporter.getMailInfoList()
$sender:=$transporter.getMail($mailInfo[0].number).from
.getMailInfo()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.getMailInfo( msgNumber : Integer ) : Object
Parameter | Type | Descrição | |
---|---|---|---|
msgNumber | Integer | -> | Número da mensagem que na lista |
Resultado | Objeto | <- | mailInfo object |
Descrição
A função .getMail()
retorna o objetomailInfo
correspondente a msgNumber na mailbox determinada pelo POP3 transporter
. Essa função permite que recupere informação sobre o email.
Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pelo método .getMailInfoList()
.
O objeto mailInfo
retornado contém as funcionalidades abaixo:
Propriedade | Type | Descrição |
---|---|---|
size | Número | Tamanho da mensagem em bytes |
id | Texto | ID única da mensagem |
O método retorna Null se:
- msgNumber designates a non-existing message,
- the message was marked for deletion using
.delete( )
.
Exemplo
var $server; $mailInfo : Object
var $mailNumber : Integer
$server.host:="pop.gmail.com" //Mandatory
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
var $transporter : 4D.POP3Transporter
$transporter:=POP3 New transporter($server)
//message info
$mailInfo:=$transporter.getMailInfo(1) //get the first mail
If($mailInfo #Null)
ALERT("First mail size is:"+String($mailInfo.size)+" bytes.")
End if
.getMailInfoList()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.getMailInfoList() : Collection
Parameter | Type | Descrição | |
---|---|---|---|
Resultado | Coleção | <- | Collection of mailInfo objects |
Descrição
A função.getMailInfoList()
retorna uma coleção de objetos mailInfo
descrevendo todas as mensagens na mailbox determinada para o POP3 transporter
. Essa função permite gerenciar localmente a lista de mensagens localizadas no servidor POP3.
Cada objeto mailInfo
na coleção retornada contém as propriedades abaixo:
Propriedade | Type | Descrição |
---|---|---|
[ ].size | Número | Tamanho da mensagem em bytes |
[ ].number | Número | Número da mensagem |
[ ].id | Texto | ID único da mensagem (útil se armazenar a mensagem localmente) |
Se a mailbox não conter uma mensagem, uma coleção vazia é retornada.
número e propriedades ID
number é o número de uma mensagem no mailbox no momento em que POP3_transporter
for criado. A propriedade number não é um valor estático em relação a qualquer mensagem específica e vai mudar de sessão a sessão dependendo de sua relação com outras mensagens no mailibox na hora em que a sessão for aberta. Os números atribuídos às mensagens só são válidos durante a duração do POP3_transporter
. No momento em que POP3_transporter
for apagado qualquer mensagem marcada para ser apagada será removida. Quando o usuário se registrar de volta no servidor, as mensagens atuais no mailbox serão numeradas de 1 a x.
Entretanto, id é um número único atribuído à mensagem quando for recebida pelo servidor. Esse número é calculado usando a hora e data que a mensagem for recebida e é um valor atribuído ao seu servidor POP3. Infelizmente, servidores POP3 não usam a referência primária id para suas mensagens. Através das sessões POP3 precisa especificar o number como a referência às mensagens no servidor. Desenvolvedores podem precisar ter cuirdado se desenvolverem soluções que trazem referências às mensagens na database mas deixam o corpo da mensagem no servidor.
Exemplo
Se quiser saber o número total e tamanho dos emails nas mailbox:
var $server : Object
$server:=New object
$server.host:="pop.gmail.com" //Mandatory
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
var $transporter : 4D.POP3Transporter
$transporter:=POP3 New transporter($server)
C_COLLECTION($mailInfo)
C_LONGINT($vNum;$vSize)
$mailInfo:=$transporter.getMailInfoList()
$vNum:=$mailInfo.length
$vSize:=$mailInfo.sum("size")
ALERT("The mailbox contains "+String($vNum)+" message(s) for "+String($vSize)+" bytes.")
.getMIMEAsBlob()
Histórico
Versão | Mudanças |
---|---|
v18 R3 | Adicionado |
.getMIMEAsBlob( msgNumber : Integer ) : Blob
Parameter | Type | Descrição | |
---|---|---|---|
msgNumber | Integer | -> | Número da mensagem que na lista |
Resultado | Blob | <- | Blob da string MIME retornado do servidor mail |
Descrição
A função .getMIMEAsBlob()
retorna uma BLOB contendo os conteúdos MIME para a mensagem correspondente a msgNumber na mailbox determinada pelo POP3_transporter
.
Passe em msgNumber o número da mensagem a recuperar. O número é retornado na propriedade número pelo método .getMailInfoList()
.
O método retorna uma BLOB vazia se:
- msgNumber designates a non-existing message,
- a mensagem foi marcada para apagar usando
.delete()
.
BLOB devolvido
.getMIMEAsBlob()
retorna um BLOB
que pode ser arquivado em um banco de dados ou convertido a um objeto Email
com o comando MAIL Convert from MIME
.
Exemplo
Se quiser saber o número total e tamanho dos emails nas mailbox:
var $server : Object
var $mailInfo : Collection
var $blob : Blob
var $transporter : 4D.POP3Transporter
$server:=New object
$server.host:="pop.gmail.com"
$server.port:=995
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"
$transporter:=POP3 New transporter($server)
$mailInfo:=$transporter.getMailInfoList()
$blob:=$transporter.getMIMEAsBlob($mailInfo[0].number)
.host
Histórico
Versão | Mudanças |
---|---|
v17 R5 | Adicionado |
.host : Text
Descrição
The .host
property contains the name or the IP address of the host server. Used for mail transactions (SMTP, POP3, IMAP).
.logFile
Histórico
Versão | Mudanças |
---|---|
v17 R5 | Adicionado |
.logFile : Text
Descrição
The .logFile
property contains the path of the extended log file defined (if any) for the mail connection. It can be relative (to the current Logs folder) or absolute.
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. For more information about extended log files, refer to:
- SMTP connections - 4DSMTPLog.txt
- POP3 connections - 4DPOP3Log.txt
- IMAP connections - 4DIMAPLog.txt
.port
Histórico
Versão | Mudanças |
---|---|
v17 R4 | Adicionado |
.port : Integer
Descrição
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
.undeleteAll()
Histórico
Versão | Mudanças |
---|---|
v18 R2 | Adicionado |
.undeleteAll() | Parameter | Type | | Descrição | | --------- | ---- |::| ------------------------------- | | | | | Does not require any parameters |
Descrição
A função .undeleteAll()
remove todas as marcações para apagar nos emails no POP3_transporter
.
.user
Histórico
Versão | Mudanças |
---|---|
v17 R4 | Adicionado |
.user : Text
Descrição
The .user
property contains the user name used for authentication on the mail server.