ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Communication / Managing emails
  • Overview
  • The different variables of the email structure
  • Acknowledgement of receipt
  • Variables of the email structure that belong to the email header
  • Which functions use the email structure?
  • The values of the Email.Error variable
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
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:
These advanced types allow you to:
WINDEV Mobile Remark: The Email structure is used by EmailRunApp/EmailOpenMail to initialize:
  • AndroidAndroid Widget the native application for sending emails found on the Android device.
  • iPhone/iPadIOS Widget the native application for sending emails found on the iPhone or iPad.
  • Universal Windows 10 App 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.AttachArray of strings containing the name of attached files.
The number of attached files is unlimited.
For more details, see
Email.AttachIdentifierArray of character strings containing the identifiers of attachments included in an HTML message.
This variable is filled when receiving an email.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.BccArray 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.CcArray 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.CertificateCertificate variable containing the certificate that will be used to sign the email before sending it.
LinuxUniversal Windows 10 AppAndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.DispositionNotificationBoolean (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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.ErrorCharacter string containing the error message.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.HTMLCharacter string containing the message with HTML formatting. Limited to 4 GB.
This member is supported by POP3/SMTP only.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.IDUnique 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
Universal Windows 10 AppAndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.KeywordsCharacter 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.MailIdentifierEmail identifier (asynchronous mode only)
WEBDEV only
Universal Windows 10 AppAndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.MessageCharacter 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.MessageIDUnique 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.NbAttachInteger indicating the number of files attached to the message. The number of attached files is unlimited.
iPhone/iPadIOS Widget Not available.
Email.NbBccInteger 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.NbCcInteger 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.NbRecipientInteger 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.OutBoolean indicating whether a message was read. Email.Out returns False when the message was read and True when the message was not read.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.PlainTextCharacter string containing the plain text of message. This variable is available for the incoming emails only.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.PriorityInteger 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.ReceiveDateDate 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.RecipientArray 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.ReferenceCharacter 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.ReturnReceiptBoolean (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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.SenderCharacter 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.SenderAddressCharacter 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.SensitivityInteger 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.
AndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.SignatureInteger 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.
LinuxUniversal Windows 10 AppAndroidAndroid Widget iPhone/iPadIOS Widget Not available.
Email.SourceCharacter string containing the source of incoming message (subject, sender, destination, content, ...).
This member is not supported by Outlook in Windows.
iPhone/iPadIOS WidgetJava Not available.
Email.SubjectCharacter 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.AttachContentDescriptionSMTP 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.AttachContentTypeSMTP 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 nameVariables used
EmailDeleteMessageEmail.Out
EmailReadFirstVariables used in read-only:
Email.SenderAddress, Email.Attach, Email.ReceiveDate, Email.Out, Email.Message, Email.NbAttach and Email.Subject
EmailReadNextVariables used in write mode:
Email.SenderAddress, Email.Attach, Email.ReceiveDate, Email.Out, Email.Message, Email.NbAttach and Email.Subject
EmailSendWhen 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.
EmailSendMessageVariables used in write mode to create the email:
Email.Attach, Email.Message, Email.Recipient, Email.NbAttach, Email.NbRecipient and Email.Subject
EmailStartSessionEmail.Error
EmailUpdateEmail.Error
The values of the Email.Error variable
After each function, the Email.Error variable contains the error report of the function:
ValueMeaning
0No error
1User-requested cancellation
2Unknown error
3Unable to connect
4Disk full
5Out of memory
6Access denied
8Too many opened sessions
9Too many attachments (up to 10 files)
10Too many recipients (up to 20 recipients)
11Attachment not found
12Unable to open the attachment
13Unable to write the attachment
14Unknown recipient
17Invalid message
18Message text too long
19Invalid session
21Ambiguous recipient address
23Network error
Related Examples:
WD Mailshot 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.
Sending emails Unit examples (WEBDEV): Sending emails
[ + ] This training example explains how to send emails with WEBDEV.
Sending an email in HTML format 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.
WD JavaMail Training (WINDEV): WD JavaMail
[ + ] This example is a Java example used to read and send emails.
WW_CMS 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.
Minimum version required
  • Version 11
This page is also available for…
Comments
Email.Recipient: UNICODE vs ANSI
Email.Recipient, as well as other recipient arrays, are UNICODE and not ANSI arrays.
So, assuming to have a local parameter arrListaDestinatari of strings, the following instructions will go into error:

1:
Email.Recipient = arrListaDestinatari

2:
FOR EACH sDestinatario OF arrListaDestinatari
   ArryAdd (Email.Recipient, sDestinatario)
END

Only these instructions will be fine:

i is int
FOR EACH sDestinatario OF arrListaDestinatari
   i ++
   Email.Recipient [i] = sDestinatario
END
Email.NbRecipient = i

In the end it is better to define a local variable:

MiaEmail is Email
MiaEmail.Recipient = arrListaDestinatari
Mister PAOLO
18 Jun. 2018

Last update: 06/23/2023

Send a report | Local help