RECEIVE-EMAIL

#### Search Results

Search

# 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-NUMBER`s 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

- Relevant Startup Parameters
  See description of `IMAP-HOST` , `IMAP-PORT` , `LIST-NUM-MAILS` and `LIST-NUM-MAILS-MAX` in Startup Parameters.

- Configuring AT-TLS
  See Configuring AT-TLS to Build a Secure Connection in z/OS Considerations.

### On this page

- Fields
- Relevant Error Codes
- Field Descriptions