GetMail and GetMailX

Retrieve an email message from the POP3 server

GetMail(MessageNR, AttLoc, MailSize, HeaderList, Text, AttList)

GetMailX(MessageNR, AttLoc, MailSize, HeaderList, Text, AttList)

Parameters

Parameter Type Direction Description
MessageNr numeric IN Number of the message to be retrieved from the POP3 server.
AttLoc string IN Directory in which any attachments contained in the retrieved email should be stored. The maximum size of this parameter is 10240 bytes.
MailSize numeric IN Maximum allowed size of a message (including attachments) that can be downloaded from the POP3 server. Set this parameter to 0 to prevent size checking from being done.
HeaderList string OUT Email header information of the retrieved email message; contains an associative list containing header-attribute pairs. The maximum size of this parameter is 10240 bytes.
Text string OUT Body of the email message. The maximum size of this parameter is 102400000 bytes (10MB).
AttList string OUT List of attachment files that have been decoded. The maximum size of this parameter is 10240 bytes.

Note:  If the MailSize, HeaderList, or AttList parameters are too large, you can retrieve the complete parameter using GetMailX iteratively by testing for $status=-16 (signature parameter size exceeded) after each activate.

Return Values

The email header information returned in HeaderList consists of an associative list containing header-attribute pairs.

Attributes Returned in Header List
Attribute name Description
ID Message identification number.
TO Email address of recipient or recipients.
FROM Email address of sender. May optionally include sender’s name.
SUBJECT Subject line of email.
DATE Date and time when message was sent.
PRIORITY Priority of the email message, in the range 1 - 5. A value of 1 means highest priority, a value of 5 means lowest priority.
CC Email addresses that the email message was also sent to.
REPLY The email address that should be used to reply to the email message.
Values returned in $status
Value Description
0 GetMail succeeded
> 0 GetMail warnings
1 The decoding of an attachment failed, but the email message itself was retrieved
2 Attachment could not be written to attachment directory
3 Duplicate attachment file name
< 0 GetMail failed
-1 Character set not supported
-4 Network time out.
-6 The size of the message text and attachment(s) exceeds the maximum size, specified in the MailSize parameter
-7 Nonvalid message number
-8 Not logged on to the POP3 server
-9 Socket error
-11 Retrieval of message failed
-16 Signature parameter size exceeded
-17 Non-supported character set.

Description

The GetMail operation retrieves a single message from a POP3 server. The message to be retrieved is specified with the MessageNR parameter.

The function GetMailX is similar to GetMail, and uses the same parameters, but should be used iteratively when the MailSize, HeaderList, or AttList parameters are too large.

Supported Character Sets

The operation retrieves emails encoded in the following Uniface-supported character sets:

  • UTF-8 (Unicode)
  • ISO-8859-1 (Western European)
  • ISO-8859-2 (Eastern European)
  • ISO-8859-4 (North European)
  • ISO-8859-5 (Cyrillic)
  • ISO-8859-7 (Greek)
  • Windows-1250 (Eastern European)
  • Windows-1251 (Cyrillic)
  • Windows-1252 (Western European)
  • Windows-1253 (Greek)
  • Windows-1255 (Hebrew)
  • Windows-1256 (Arabic)
  • ISO-2022-jp (Japanese)
  • EUC-KR (Korean)
  • KSC5601-1992 (Korean)
  • GB2312 (Simplified Chinese)
  • BIG5 (Traditional Chinese)

These are converted to UTF-8 format. When a character set is encountered that is not supported, the error -17 is returned. You can use GetRawMail to retrieve the email's raw content.

Multipart Messages

An email message can have a multipart structure. For example, the MIME structure of a typical HTML email with an inline image and an attachment will be: 

multipart/mixed
    + multipart/alternative
        + text/plain
        + multipart/related
            + text/html
            + inline image
    + attachment

or

multipart/mixed
    + multipart/related
        + multipart/alternative
            + text/plain
            + text/html
        + inline image
    + attachment

The GetMail and GetMailX operations are able to get only one text plus attachments as return values. If the email contains more than one text, for example one plain text and one html text, the plain text part is returned as the text and the html text is extracted as the attachment file. The inline images are also extracted as attachment file. In short, any multipart other than the plain text, will be retrieved as attachment files.

Examples

activate "UPOPMAIL".GetMail (MESSAGEID.RECEIVED,ATTACHDIR.RECEIVED,SIZE.RECEIVED,HEADER.RECEIVED, MAILTEXT.RECEIVED, ATTACHED.RECEIVED)
if ($status = -16)  
  activate "UPOPMAIL".GetMailX(MESSAGEID.RECEIVED,ATTACHDIR.RECEIVED,SIZE.RECEIVED,HEADER.RECEIVED, vMessagePart, ATTACHED.RECEIVED))
  if (MAILTEXT.RECEIVED)
    MAILTEXT.RECEIVED = "%%MAILTEXT.RECEIVED%%vMessagePart"
  else
    MAILTEXT.RECEIVED = vMessagePart
  endif
endwhile

Related Topics