EMAIL2 Configuration Service Provider

4/8/2010

Mobile operators and OEMs can use the EMAIL2 Configuration Service Provider to configure Simple Mail Transfer Protocol (SMTP) e-mail accounts for devices running Windows Mobile 2003 and later.

When you provision an application removal or configuration roll-back, the EMAIL2 Configuration Service Provider passes the request to Configuration Manager, which handles the transaction externally. When you remove a MAPI application, the accounts that were created with it are deleted. If you attempt to create a new e-mail account, and you are unsuccessful, the new account is automatically deleted. If you attempt to edit an existing account, and you are unsuccessful, the original configuration is automatically rolled back (restored).

You can also use this Configuration Service Provider to enable Secure Sockets Layer (SSL) for incoming and outgoing e-mail servers. To do so, use an unnamed tag: <parm name="8128000B" value="1"> for the incoming server, and <parm name="812C000B" value="1"> for the outgoing server. For more information, see Enabling SSL Example.

For more information about SSL, see SSL Support.

The following table shows the default settings. The default security role maps to each subnode unless specific permission is granted to the subnode.

Security Note:
Configuration data is not encrypted when sent over the air (OTA). Be aware that this is a potential security risk when sending sensitive configuration data, such as passwords.

The following diagram illustrates the EMAIL2 Configuration Service Provider schema used in OMA DM.

The following diagram illustrates the EMAIL2 Configuration Service Provider schema used in OMA Client Provisioning.

Characteristics

• EMAIL2
  The encapsulating characteristic for all the other e-mail service provisioning elements (groups all e-mail services in the provisioning document).

• <GUID>
  Defines one specific e-mail account. This is a globally unique identifier (GUID) that you must generate for each new account.

  Note

  When managing over OMA DM, make sure to always use a unique GUID. Provisioning with an account that has the same GUID as an existing one deletes the existing account and does not create the new account.

  Note

  Brackets {} are required around the GUID in the EMAIL2 Configuration Service Provider. In OMA Client Provisioning, you can type the brackets, for example, <characteristic type="{C556E16F-56C4-4edb-9C64-D9469EE1FBE0}"/>. For OMA DM, you must use the ASCII values of 0x7B and 0x7D respectively. For example, if the GUID is "C556E16F-56C4-4edb-9C64-D9469EE1FBE0," you would type <Target><LocURI>./Vendor/MSFT/EMAIL2/0x7BC556E16F-56C4-4edb-9C64-D9469EE1FBE0x7D</LocURI></Target>

• NAMEDPROPS
  Specifies that you are stating parameter element name attributes as nonstandard named properties. Used to group together parameters that are identified by a combination of MAPI property names and types.

• TAGPROPS
  Specifies that you are stating parameter element name attributes as nonstandard tag properties. Used to group together parameters that are identified by MAPI property tags.

Parameters

• 8128000B
  Used to enable the incoming server for SSL. A value of 1 indicates that SSL is enabled; a zero (0) indicates that it is not enabled. For an example, see Enabling SSL Example.

• 812C000B
  Used to enable the outgoing server for SSL. A value of 1 indicates that SSL is enabled; a zero (0) indicates that it is not enabled. For an example, see Enabling SSL Example.

• AUTHNAME
  [Required] The name used to authorize the user to a specific e-mail account (also known as the user's logon name).

• AUTHREQUIRED
  [Optional] Specifies whether the outgoing server requires authentication (1 for TRUE, and 0 for FALSE).

• AUTHSECRET
  [Optional] The user's password. The same password is used for SMTP authentication.

• CONNECTIONID
  [Optional] The network connection GUID. The CONNECTIONID parameter must appear immediately beneath the <GUID> characteristic. If you do not include the CONNECTIONID parameter, the mobile device will attempt to find the best connection automatically.

• DOMAIN
  [Optional] The user's domain name.

• DWNDAY
  [Optional] How much e-mail to download. This is the number of days' worth, going back into the past. Use a value of -1 (or 4294967295) to specify that you want to download all of the messages that are currently on the server.

• FORMAT
  [Optional] Specifies which format to use for downloading and composing new e-mail messages (1 for Plain Text, and 2 for HTML). The default is HTML.

• INSERVER
  [Required] The name of the messaging service's incoming e-mail server.

• KEEPMAX
  [Optional] Specifies the maximum size (in KB) for message attachments to be downloaded. Attachments that are larger will remain on the server, but the message itself will still be downloaded. Use a value of 0 to specify that you do not want any message attachments. Use a value of -1 (or 4294967295) to specify that you want all message attachments, no matter how large.

• LINGER
  [Optional] Frequency that Microsoft Outlook uses to perform scheduled sends/receives. The frequency is specified as the length of time between updates, in minutes.

  Note

  If a value is not provided for LINGER, the automatic connection sync setting defaults to every 15 minutes. You should set the LINGER parameter to 0 to never connect automatically.

• NAME
  [Optional] The display name associated with the user's e-mail account.

• OUTSERVER
  [Required] The name of the messaging service's outgoing e-mail server.

• REPLYADDR
  [Required] The user's reply e-mail address (usually the same as the user's e-mail address).

• RETRIEVE
  [Optional] Specifies the maximum size (in bytes) for messages retrieved from the incoming e-mail server. Messages beyond this size will still be retrieved, but will be truncated. Use a value of 0 to specify that you only want to download headers. Use a value of -1 (or 4294967295) to specify that you want to download the full messages.

• SERVICENAME
  [Required] The name of the e-mail service to create or edit, 32 characters maximum.

  Note

  The Email2 Configuration Service Provider does not support the OMA DM Replace command on the parameters SERVICENAME and SERVICETYPE. To replace either the e-mail account name or the account service type, you must delete the existing e-mail account, and then create a new one.

• SERVICETYPE
  [Required] The type of e-mail service to create or edit (such as IMAP4 or POP3).

  Note

  The Email2 Configuration Service Provider does not support the OMA DM Replace command on the parameters SERVICENAME and SERVICETYPE. To replace either the e-mail account name or the account service type, you must delete the existing e-mail account, and then create a new one.

• SMTPALTAUTHNAME
  [Optional] Display name associated with the user's alternative SMTP e-mail account; only valid if SMTPALTENABLED is True.

• SMTPALTDOMAIN
  [Optional] User's domain name for the alternative SMTP account; only valid if SMTPALTENABLED is True.

• SMTPALTENABLED
  [Optional] A Boolean value that indicates that an alternative SMTP server is enabled.

• SMTPALTPASSWORD
  [Optional] Password for the alternative SMTP account; only valid if SMTPALTENABLED is True.

Microsoft Custom Elements

The following table shows the Microsoft custom elements that this Configuration Service Provider supports for OMA Client Provisioning.

Use these elements to build standard OMA Client Provisioning configuration XML. For information about specific elements, see MSPROV DTD Elements. For general examples of how to use the Microsoft custom elements, see OMA Client Provisioning XML File Examples.

For information about OMA Client Provisioning, see OMA Client Provisioning Files.

Remarks

If you want to configure a Windows Mobile device so that it can use Server ActiveSync to synchronize all types of Microsoft Exchange server objects (rather than just e-mail), use the Sync Configuration Service Provider.

Access to this Configuration Service Provider is determined by Security roles. Because OEMs and Mobile Operators can selectively disallow access, ask them about the availability of this Configuration Service Provider. For more information about roles, see Security Roles and Default Roles for Configuration Service Providers.

For OMA DM, the EMAIL2 Configuration Service Provider handles the Replace command differently from most other Configuration Service Providers. For the EMAIL2 Configuration Service Provider, Configuration Manager implicitly adds the missing part of the node to be replaced or any segment in the path of the node if it is left out in the <LocURI></LocURI> block. There are separate parameters defined for the outgoing server logon credentials. The following are the usage rules for these credentials:

• Continue to use the incoming server logon credentials (AUTHNAME, AUTHSECRET, DOMAIN) unless the outgoing server credentials are set.
• If some but not all of the outgoing server credentials parameters are present then the EMAIL2 Configuration Service Provider will be considered in error.
• You cannot query for account details unless you already know the account GUID (currently, there is no way to perform a top-level query for account GUIDs).

See Also

Tasks

EMAIL2 Configuration Service Provider Examples for OMA Client Provisioning

Concepts

Configuration Service Provider Reference for Windows Mobile Devices

Other Resources

EMAIL2 Configuration Service Provider Examples for OMA DM
EMAIL2 Configuration Service Provider Mapping to OMA DM E-mail XML