Collapse all Symbian^3 Product Developer Library

Email Settings

The Email collection provides IMAP MTM, POP3 MTM and SMTP MTM components to support the IMAP4, POP3 and SMTP email protocols respectively. These components provide APIs to modify configuration settings of an email MTM.

The configuration settings are broadly classified as below:

Service settings: Allows the messaging client to modify the settings parameters and save them.
Internet Access Provider (IAP) preferences setting: Allows the messaging client to modify the IAP preferences and save them.
SNAP preferences: Allows the messaging client to set a SNAP identifier to use for internet access.

Service settings

These settings can be modified by the functions provided by the Email MTM component. Applicable settings for protocols are marked.

Setting	Description	SMTP	POP3	IMAP4
Acknowledge receipts	If the sender of an email message has requested a receipt notification, the messaging client can check this setting and compose a receipt notification message.	-	Supported	Supported
Bearer Mobility	If enabled, indicates that the email service shall attempt a bearer migration when a preferred carrier becomes available (upgrade), or when the carrier over which an existing connection has been made becomes unavailable (downgrade). The following is the default migration: upgrade: allow any outstanding operation to complete, then attempt to switch to the new bearer. downgrade: immediately close connected sockets, then attempt to switch to the new bearer. Any operations in progress at the time of the migration is resumed when connection has been made through the new carrier. The default policy is plug-in replaceable, allowing migration notices to be ignored or modifying the handling of outstanding operations, which may be suspended and resumed following the migration. Note that Bearer Mobility can only be performed when the account connection preferences specify a SNAP, see Bearer Mobility.	Supported	Supported	Supported
Body encoding	Specifies the encoding used when sending an email message.	Supported	-	-
Default character set	Sets the character set of the out-bound email message.	Supported	-	-
Disable IMAP Folder Tree Synchronisation	Specifies whether the remote folder tree shall be synchronised as part of account synchronisation operations. The default setting is `EFalse`, which means that the folder tree synchronisation shall be performed.	-	-	Supported
Disconnected user mode	If enabled, allows the messaging client to fetch, move, and delete mailbox messages while not connected by queuing offline operations. The queued offline operations are automatically processed the next time the messaging client connects, just before login and Inbox synchronisation. For the IMAP4 protocol, messages are not marked as invisible when disconnected if this setting is enabled.	-	Supported	Supported
Email address	The email address of the subscriber.	Supported	-	-
Email alias	The name of the subscriber as they want it to appear in the header of the email messages they send.	Supported	-	-
Folder path	The path to the IMAP4 mailbox on the server if the subscriber’s primary mailbox is not the Inbox. Note: Most messaging clients need not have to set this. Refer to RFC 3501, Section 5.1 Mailbox naming for more information.	-	-	Supported
Get Mail Options	Specifies how new messages must be fetched when synchronising. The available options are: Headers only Body text only (applicable to IMAP4 only) Attachments only (applicable to IMAP4 only) Entire message	-	Supported	Supported
IMAP IDLE	Specifies whether the IMAP IDLE command must be used as defined in RFC2177. The default setting is `ETrue` which means that the IMAP IDLE command is used, if the server supports it.	-	-	Supported
IMAP IDLE timeout	Specifies the IMAP IDLE timeout in seconds. The default setting is 1740 seconds (29 minutes).	-	-	Supported
IMAP Synchronisation Download Rules	Specifies which message parts to automatically download when synchronising the contents of an IMAP email account. See IMAP Account Settings for more information.	-	-	Supported
IMAP Transport Buffer Sizes	Allows a client to configure transport buffer sizes of IMAP accounts according to bearer type for fetching of large message parts. It is possible to specify: maximum fetch size (default is 20480 octets) maximum outstanding fetch requests (default is 2 outstanding requests) Note that this is a global setting that affects all IMAP accounts.	-	-	Supported
Inbox refresh rate	Specifies whether to periodically poll the email server for new messages, and if so, how frequently.	-	-	Supported
Inbox synchronisation limit	Sets the limit (if any) for the number message headers stored in the Inbox of the local device when synchronising. Older message headers are deleted to make space for newer message headers. Messages that have had body text or attachments downloaded will not be deleted and are not considered part of the Inbox count limit. Can also be used to disable Inbox synchronisation after a connection.	-	Supported	Supported
Include signature	If the subscriber has a signature, it is append the body text of out-bound email messages.	Supported	-	-
Include VCard	If the subscriber has a VCard, the VCard is attached to out-bound email messages.	Supported	-	-
Login name	The subscriber’s login name.	Supported	Supported	Supported
Login password	The subscriber’s login password.	Supported	Supported	Supported
Mailbox synchronisation limit	Sets the limit (if any) for the number of messages headers stored in non-Inbox folders on the local device when synchronising. Older message headers are deleted to make space for newer message headers. Messages that have had body text or attachments downloaded will not be deleted and are not considered part of the non-Inbox count limit. Can also be used to disable folder synchronisation.	-	-	Supported
Maximum email size	Allows the messaging client to specify a maximum size (if any) in KB that are downloaded. If the email is larger than the maximum size, none of its body text or attachments are downloaded.	-	Supported	Supported
Path separator	Allows the messaging client to specify the character used to separate hierarchical mailbox names on the IMAP4 server. Refer to RFC 3501 section 5.1.1 for more information.	-	-	Supported
Reply-to address	The email address that the subscriber wishes any replies to their email messages to be sent to. However, it is possible to override this on a per message basis when composing the message.	Supported	-	-
Request receipt	If enabled, sent messages indicates to the receiving messaging client that they want a receipt notification message (for example, a read notification) sent back to the email address specified in the receipt address setting. It is entirely up to the receiving messaging client whether it complies with this request.	Supported	-	-
Receipt address	The email address that message receipt notifications is sent to if request receipts has been enabled.	Supported	-	-
Secure sockets	If enabled, a secure TLS connection is negotiated over an un-secure socket on the specified server port according to RFC 2595 and 3207 specifications.	Supported	Supported	Supported
Send copy to self	Specifies how copies of messages must be send to the sender. The available options are: Do not send a copy Send a copy by including the sender’s email address in the To recipients of the email to be sent Send a copy by including the sender’s email address in the Cc recipients of the email to be sent Send a copy by including the sender’s email address in the Bcc recipients of the email to be sent	Supported	-	-
Send message options	Specifies how the message is sent. The available options are: Send messages next time the subscriber connects to their mailbox Send messages immediately Send messages when messaging client requests	Supported	-	-
Server address	The hostname or IP address of the SMTP, IMAP4, or POP3 server.	Supported	Supported	Supported
Server port	The TCP port of the SMTP, IMAP4, or POP3 server.	Supported	Supported	Supported
Size Limiting of emails	If body text size limit is specified, then downloads the body text of a email partially and downloads the attachments only if their size is less than or equal to the specified attachment size limit.	-	-	Supported
SMTP Account Override	Allows the client to associate “SMTP Mobility Accounts” with an SMTP account, to use when connected through specified internet access points. When attempting to send an email using SMTP, the IAP that the connection to the SMTP server is using is checked. If a SMTP mobility account is specified for that IAP, then the settings for that SMTP mobility account is used to send the email. If no SMTP mobility account is specified for that IAP, then the settings from the SMTP account is used. Only settings relating to the sending of emails are overridden – emails are constructed according to the over-ridden SMTP account settings.	Supported	-	-
SSL wrapper	If enabled, a secure TLS connection is established on the specified server port.	Supported	Supported	Supported
TLS/SSL Domain	Specifies the domain to use for certificate validation when establishing a secure TLS connection.	Supported	Supported	Supported
Update flags	If enabled, the seen flag is updated on the IMAP4 mailbox for messages that have been read. This indicates to email applications on other devices accessing the same mailbox that the message has already been read. Likewise, if an email application on another device marks messages as read on the server, then the messaging client indicates that the message has already been read.	-	-	Supported
Use APOP authentication	Specifies whether to use APOP authentication to login to the POP3 mailbox.	-	Supported	-
Use SMTP authentication	Specifies whether to use SMTP AUTHentication to login to the SMTP server.	Supported	-	-

SNAP Preferences

A allow Service Network Access Point (SNAP) is a collection of access points (AP) that are used especially for bearer mobility to identify a service network with a service to be accessed on the network. That is, it is a collection of IAP that specify the same network and the same service on that network. SNAP uses the underlying Networking framework to select the best AP defined in the SNAP preference list to use to establish the connection.

The CImIAPPreferences class encapsulates preferences about IAPs for an email service. This class allows a single SNAP to be specified as an alternative to a list of preferred IAPs. A SNAP defines its own list of IAPs in preference order, and is reusable by multiple clients that requires network connections.

To allow SNAP IDs to be defined, retrieved, and deleted when a network connection is made, the following functions are provided by the CImIAPPreferences class:

SMTP account override settings

The SMTP account override functionality allows the messaging client to associate SMTP mobility accounts with an SMTP account to use when connected through the specified Internet access points.

A SMTP mobility account allows different send settings to be used by SMTP accounts depending on what access point is being used by the SMTP connection. When a connection is made for a SMTP account, its associated list of SMTP mobility accounts is examined to check, if any access point is linked to the bearer type that is used for the connection. If any access point is found, then the settings for the SMTP mobility account are used for the connection and subsequent email sending in preference to the settings for the SMTP account.

To override the SMTP mobility account settings, the following class are provided. These classes describe the settings that are overridden when connecting to the mobility account through an IAP associated with the mobility account.

TLS or SSL domain name for certificate validation

To enhance certification security checks, the CImBaseEmailSettings class is enhanced to allow the Transport Layer Security (TLS) or Secure Sockets Layer (SSL) server domain name to be specified when creating email accounts. The following functions are added to the CImBaseEmailSettings class:

IAP preferences setting

Tittle	Description
IAP Number	The IAP identifier as specified in the CommDb record for the IAP.
Dialogue Preference	The dialog preference determines whether a user must be prompted with a dialog when connecting to the IAP. The available options are: Prompt Warn Do not prompt Prompt if wrong mode

Tittle

Description

IAP Number

The IAP identifier as specified in the CommDb record for the IAP.

Dialogue Preference

The dialog preference determines whether a user must be prompted with a dialog when connecting to the IAP.

The available options are:

Prompt
Warn
Do not prompt
Prompt if wrong mode

Email settings example

Parent topic: Email Concepts

Related concepts

Bearer Mobility

Processing Email in Chunks