The email structure

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help

WLanguage

WLanguage functions

Communication

Managing emails

Prefix syntax

WLanguage functions

The email structure

Overview

The different variables of the email structure

Which functions use the email structure?

The values of the Email.Error variable

Related examples

See also

The email structure

Warning
The email structure is kept for backward compatibility, and to be used in PHP. In most cases, it is recommended to use a variable of type Email.

Overview

The email structure is a preset structure of WLanguage (no declaration is required). This structure is used to:

create an email,
retrieve the content of emails.

To reset all variables of Email structure to zero, use EmailReset.

The Email structure proposes a simple method for handling an email. You also have the ability to use the advanced types for handling emails:

Email variable.
emailAttach variable.

These advanced types allow you to:

handle several emails simultaneously.
use Serialize/Deserialize on the email.
use the Data binding.
use the FOR ALL loops on the email sessions.
...

Remark: The Email structure is used by EmailRunApp/EmailOpenMail to initialize:

the native application for sending emails found on the Android device.
the native application for sending emails found on the iPhone or iPad.
the native application for sending emails found on the mobile in Universal Windows 10 App mode.

The different variables of the email structure

The structure contains the following members:

Remark: The limits specified in this table only apply to the MS Exchange client. When using the POP3/SMTP protocol, the limits are the ones given by the server.


Email.Attach	Array of strings containing the name of attached files. The number of attached files is unlimited. For more details, see Reading an email. Writing an email.
Email.AttachIdentifier	Array of character strings containing the identifiers of attachments included in an HTML message. This variable is filled when receiving an email. Not available.
Email.Bcc	Array of strings containing the addresses of the non-official recipients: their name is not displayed in the email received by the official recipients (Email.Recipient variable). The addresses are limited to 127 characters. The number of non-official recipients is limited to 200. This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.Cc	Array of strings containing the addresses of the copied recipients: their name is not displayed in the email received by the official recipients (Email.Recipient variable). The addresses are limited to 127 characters. The number of non-official recipients is limited to 200. This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.Certificate	Certificate variable containing the certificate that will be used to sign the email before sending it. Not available.
Email.DispositionNotification	Boolean (False by default) Outbound, used to request a confirmation that the email was read by the recipient. The recipient does not necessarily have to send a read receipt. Inbound, used to find out whether a read receipt was requested by the sender. If a read receipt is requested, it has priority over the delivery receipt. This member is not supported by Lotus Notes. This member is supported by Outlook in Windows. Not available.
Email.Error	Character string containing the error message. Not available.
Email.HTML	Character string containing the message with HTML formatting. Limited to 4 GB. This member is supported by POP3/SMTP only. Not available.
Email.ID	Unique email identifier (character string). This identifier remains constant for the entire email lifetime. This identifier is initialized when sending the email (EmailSendMessage). Remark: If the identifier contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage. Outlook and Lotus Notes messaging software only Not available.
Email.Keywords	Character string containing a list of keywords associated with the email. The keywords are separated by semicolons. Remark: If a keyword contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage. Not available.
Email.MailIdentifier	Email identifier (asynchronous mode only) WEBDEV only Not available.
Email.Message	Character string containing the text of message (with simple text formatting). Limited to 2 GB (64 KB for Lotus Notes). Remark: If the message contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage.
Email.MessageID	Unique email identifier (character string). This identifier remains constant for the entire email lifetime. This identifier is used to follow a conversation. When sending an email, this variable specifies the email identifier. If this variable corresponds to an empty string, the identifier will be given by the server. The application that generates the identifier must manage the uniqueness of this identifier. This variable is taken into account only if the EmailOptionMessageID constant is used in EmailSendMessage. When receiving an email, this variable specifies the email identifier. This identifier must have the following format: <Identifier@domain>. For example: 1@192.168.2.210 This member is not supported by Lotus Notes. This member is not supported by Outlook in Windows. Not available.
Email.NbAttach	Integer indicating the number of files attached to the message. The number of attached files is unlimited. Not available.
Email.NbBcc	Integer corresponding to the number of non-official recipients (limited to 200). This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.NbCc	Integer corresponding to the number of copied recipients (limited to 200). This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.NbRecipient	Integer containing the number of recipients for the message. The number of recipients is limited to 20. This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.Out	Boolean indicating whether a message was read. Email.Out returns False when the message was read and True when the message was not read. Not available.
Email.PlainText	Character string containing the plain text of message. This variable is available for the incoming emails only. Not available.
Email.Priority	Integer constant containing the type of priority for the email. The possible values are as follows: *emailLowPriority: used for the really non-urgent emails. emailHighPriority: used for the urgent emails. emailNormalPriority* (Default value): used for the non-urgent emails. Caution: This member is supported by POP3/SMTP only. Not available.
Email.ReceiveDate	Date when the message was received (128 characters). If the email session was started by: EmailStartSession: the format of the date depends on the language used by Windows on the current computer. EmailStartOutlookSession: the format of the date is as follows: YYYYMMDDHHSSCCmmm. The time is in UTC format. Not available.
Email.Recipient	Array of character strings containing the addresses of the main recipients. The copied recipients and the blind copied recipients are ignored. The number of recipients is limited to 20. This limit can be exceeded in SMTP mode. However, some servers do not support the emails with an important number of recipients.
Email.Reference	Character string. Unique identifier of one or more reference emails linked to the current conversation. This member is not supported by Lotus Notes. This member is not supported by Outlook in Windows. Not available.
Email.ReturnReceipt	Boolean (False by default). In outgoing mode, requests a delivery receipt from the recipient. The recipient does not necessarily have to send a delivery receipt. In incoming mode, determines whether a delivery receipt was requested by the sender. If a read receipt is requested, it has priority over the delivery receipt. This member is not supported by Outlook in Windows. Not available.
Email.Sender	Character string containing the sender address. In Lotus, the Lotus username is used if the sender is not specified. Remark: If the sender contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage. Not available.
Email.SenderAddress	Character string containing the address where the answer to the message must be sent (up to 127 character). Corresponds to Reply-To. In Outlook, this variable is ignored. The account name of the current session is used to specify this variable. In Lotus, the Lotus username is used if the sender is not specified. Remark: If the address contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage. Not available.
Email.Sensitivity	Integer constant containing the type of confidentiality for the email. The possible values are as follows: *emailCompanyConfidential: Used for the in-house emails for example. emailNoSensitivity* (Default value): No confidentiality. *emailPersonal: Used for the personal emails for example. emailPrivate*: Used for the private emails for example. This member is not supported by Lotus Notes. Not available.
Email.Signature	Integer constant corresponding to the status of the email signature: *certificateExpired: Valid signature but expired certificate. certificateInvalid: Invalid signature or certificate. certificateUntrusted: Valid signature but untrusted certificate root. certificateOK*: Trusted signature and certificate. Not available.
Email.Source	Character string containing the source of incoming message (subject, sender, destination, content, ...). This member is not supported by Outlook in Windows. Not available.
Email.Subject	Character string containing the message subject. Remark: If the subject contains special characters or accented characters, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage.

Advanced management of emails (SMTP mode only): To perform an advanced description of the emails, you have the ability to access the MIME Content-Type and Content-Description controls for each attachment supplied with the email.

The corresponding variables are as follows:


Email.AttachContentDescription	SMTP mode only Array of strings corresponding to the content of MIME Content-description control of each attached file. The number of attached files is unlimited.
Email.AttachContentType	SMTP mode only Array of strings corresponding to the content of MIME Content-type control of each attached file. The number of attached files is unlimited.

These variables are accessible in read-only when receiving an email and in read/write when sending an email.

Remarks:

If Email.Message and Email.HTML are empty and if the email has a single attachment, the MIME content-Type and Content-description controls will correspond to the characteristics of the attached file.

You can use non-Latin characters in the following variables:
- Email.Subject
- Email.Message
- Email.Keywords
- Email.SenderAddress
- Email.Sender
- Email.ID
In this case, use the emailOptionEncodeHeader constant when the message is sent by EmailSendMessage.

Acknowledgement of receipt

Two variables can be used to managed an acknowledgment of receipt: Email.DispositionNotification and Email.ReturnReceipt.

Some email software only recognize Email.DispositionNotification, other recognize both variables and perform specific operations according to the variable used.

Email.DispositionNotification is the most recognized variable while Email.ReturnReceipt is less and less recognized.

To remain compatible with the email software that use the second variable, the 2 variables are kept and differentiated. We recommend that you use these two variables (the main variable being Email.DispositionNotification).

Variables of the email structure that belong to the email header

When reading the header of the email, the email structure is automatically updated according to the content of the message header.
The following variables are empty:

Email.Message
Email.Attach
Email.NbAttach
Email.HTML
Email.PlainText

These variables require a full reading of the message (EmailReadMessage). The Email.Bcc and Email.NbBcc variables can only be used to send emails.

Which functions use the email structure?

The following functions use the email structure:

Function name	Variables used

EmailDeleteMessage	Email.Out
EmailReadFirst	Variables used in read-only: Email.SenderAddress, Email.Attach, Email.ReceiveDate, Email.Out, Email.Message, Email.NbAttach and Email.Subject
EmailReadNext	Variables used in write mode: Email.SenderAddress, Email.Attach, Email.ReceiveDate, Email.Out, Email.Message, Email.NbAttach and Email.Subject
EmailSend	When sending the email, only the variables of the email structure required by the SMTP protocol are taken into account. The other variables are ignored. Variables used: Email.CC, Email.Recipient, Email.Sender, Email.NbCc, Email.NbRecipient.
EmailSendMessage	Variables used in write mode to create the email: Email.Attach, Email.Message, Email.Recipient, Email.NbAttach, Email.NbRecipient and Email.Subject
EmailStartSession	Email.Error
EmailUpdate	Email.Error

The values of the Email.Error variable

After each function, the Email.Error variable contains the error report of the function:

Value	Meaning

0	No error
1	User-requested cancellation
2	Unknown error
3	Unable to connect
4	Disk full
5	Out of memory
6	Access denied
8	Too many opened sessions
9	Too many attachments (up to 10 files)
10	Too many recipients (up to 20 recipients)
11	Attachment not found
12	Unable to open the attachment
13	Unable to write the attachment
14	Unknown recipient
17	Invalid message
18	Message text too long
19	Invalid session
21	Ambiguous recipient address
23	Network error

Related Examples:

Training (WINDEV): WD Mailshot

[ + ] This example explains how to send a mailshot with WINDEV.

This example is used to type the subject of the message, its content and its attachments.
Then, the user must select the customers to which the message will be sent.
The WLanguge EmailSendMessage() function is used to send the message to each selected customer.
Technical implementation:
An email server compatible with POP3/SMTP must necessarily be accessible from the computer on which the application is run.

Unit examples (WEBDEV): Sending emails

[ + ] This training example explains how to send emails with WEBDEV.

Unit examples (WINDEV): Sending an email in HTML format

[ + ] Using the WLanguage "EmailImportHTML" function.
This function is used to import an HTML file into the email structure. This allows you to easily add images into the emails.

Training (WINDEV): WD JavaMail

[ + ] This example is a Java example used to read and send emails.

Complete examples (WEBDEV): WW_CMS

[ + ] This example is an example of CMS (Content Management System).
This is a site for content management, typically a site for displaying some articles.

This example is divided into 2 parts:
- An AWP part for the part that must be referenced
- A WEBDEV part for the management part

Note:
In order for some features of the example to operate (sending emails for example), the parameters must be modified in order to adapt them to your configuration.
These parameters are stored as constants defined in the code of the project.