RECEIVE-EMAIL

File 70
Op-Sys z/OS
Statement FIND
Task This view provides the support for receiving e-mails using IMAP protocol

Fields

Dictionary Field Name F/L Mu DE Remarks
DATE A64   D Date and Time a mail was transmitted to the sender's mail server.
FUNCTION A8   D Function to be performed.
LIST-NUM-MAILS N3.0   D Number of mails to be processed by one call of the LIST function. Also defined as startup parameter.
LIST-NUM-MAILS-START N6.0   D Sequence number the LIST function starts on its second or nth call.
MAIL-SEQUENCE-NUMBER N6.0     Internal number; can change after call.
MAILSERVER-RESPONSE A128      Response of mail server in case an error had occurred.
MESSAGE-ID A128   D Internal identifier.
NUMBER-MAILS N5.0     Number of mails in inbox.
NUMBER-NEW-MAILS N5.0     Number of unread mails in inbox.
PASSWORD A64   D Password of caller.
RECIPIENTS A250   D List of recipients.
RECORD A253   D Mail body.
SENDER-MAIL A64   D E-Mail address of sender.
SENDER-NAME A64   D Name of sender.
STATUS A4   D NEW for unread mails, SEEN for mails already read.
SUBJECT A128   D Subject of e-mail.
TRACE A4   D YES/NO. If set to YES, the contents of the mail is traced.
UID N12.0   D Unique identifier. Key to read or delete a mail.
USERID A64   D User ID of caller or e-mail address.

Relevant Error Codes

Code Text
600 unknown function
927 init error
928 LOGON error
929 no connection with remote host
930 LIST-NUM-MAILS greater max
931 error with command
932 record length invalid
933 UID missing
934 Mail not found

Field Descriptions

Field Name Type/Length Operating System
DATE (A64) z/OS

Time and date at which an e-mail was sent. The format of this field depends on the data of mail sender.

Field Name Type/Length Operating System
FUNCTION (A8) z/OS

Function to be performed. Possible options:

Option Explanation
DELETE Delete a mail. See example.
LIST Display directory data of mails such as STATUS, SENDER-MAIL, SENDER-NAME, SUBJECT, RECIPIENTS, MESSAGE-ID, UID or DATE. See example.
READ Read a mail. See example.
STATUS Request total number of mails (NUMBER-MAILS) and/or number of new mails (NUMBER-NEW-MAILS). See example.
Field Name Type/Length Operating System
LIST-NUM-MAILS (N3.0) z/OS

Number of mails displayed by function LIST. This field is also defined as startup parameter which defaults to 20. The maximum to be specified is controlled by startup parameter LIST-NUM-MAILS-MAX. The default is 100. The maximum is 999.

Field Name Type/Length Operating System
LIST-NUM-MAILS-START (N6.0) z/OS

This field is used for function LIST to control the position from which to read in mails, by default the position of the latest mail. Note that mails are ordered according to the date they have been received.

Field Name Type/Length Operating System
MAIL-SEQUENCE-NUMBER (N6.0) z/OS

Number indicating the current position of the mail in the mailbox. If a mail is deleted or a new mail arrives the MAIL-SEQUENCE-NUMBERs are recomputed.

Field Name Type/Length Operating System
MESSAGE-ID (A128) z/OS

A unique world-wide reference for e-mails. However, a MESSAGE-ID cannot be used to read or delete a mail. Use UID instead.

Field Name Type/Length Operating System
MAILSERVER-RESPONSE (A128 ) z/OS

The message of the mail server if an error has occurred.

Field Name Type/Length Operating System
NUMBER-MAILS (N5.0) z/OS

Number of mails contained in the mailbox

Field Name Type/Length Operating System
NUMBER-NEW-MAILS (N5.0) z/OS

Number of mails that have not been read yet that is those with attribute NEW.

Field Name Type/Length Operating System
PASSWORD (A64) z/OS

Password for the e-mail account, handed over in the Natural program.

Field Name Type/Length Operating System
RECIPIENTS (A250) z/OS

The list of recipients of a mail. This can be one recipient indicated by a name and an email address, multiple recipients or a mailing list. Note that the list can only contain 250 characters and that the list is truncated if this limit is exceeded. This field is optional.

Field Name Type/Length Operating System
RECORD (A253) z/OS

Lines of text contained in the body of a mail. We recommend to use plain text / 7-bit ASCII because there is only a basic ASCII-EBCEDIC conversion and no character encoding recognition to recognize for example UTF-8. An HTML mail will be displayed without formatting that is with HTML codes.

Field Name Type/Length Operating System
SENDER-MAIL (A64) z/OS

The e-mail address of the sender of a mail. This field is optional.

Field Name Type/Length Operating System
SENDER-Name (A64) z/OS

The name of the sender of a mail. This field is optional.

Field Name Type/Length Operating System
STATUS (A4) z/OS

Specifies either NEW for a mail that is new or SEEN for a mail that has already been read. This field is optional.

Field Name Type/Length Operating System
SUBJECT (A128) z/OS

Specifies the subject of the mail. This field is optional.

Field Name Type/Length Operating System
TRACE (A4) z/OS

If Software AG support

If set to YES, a trace also includes net data from a mail. If set NO (default) or if left blank, tracing includes technical data.

Field Name Type/Length Operating System
UID (N12.0) z/OS

Specifies the unique identifier of a mail. A UID is displayed using the LIST function. A UID is needed to uniquely identify a mail so it can be read or deleted. The MAIL-SEQUENCE-NUMBER cannot be used for this.

Field Name Type/Length Operating System
USERID (A64) z/OS

User ID for the e-mail account, handed over in the Natural program.

Examples

See Receiving Emails in Entire System Server at Work - Examples

Supplementary Information about RECEIVE-EMAIL