EMAIL2 Configuration Service Provider

Article
08/28/2006

can use the E-Mail2 Configuration Service Provider (CSP) to configure Simple Mail Transfer Protocol (SMTP) e-mail accounts.for Windows Mobile–based devices running Windows Mobile 2003 or 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).

Note All messages and other properties that the transport (Short Message Service [SMS], Post Office Protocol [POP], Simple Mail Transfer Protocol [SMTP], and so on) might have stored, are lost.

You can also use this configuration service provider to enable Secure Sockets Layer (SSL) for incoming and outgoing E-mail Servers. To do this, 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.

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

Permissions	Read/write
Roles allowed to query and update setting	Manager AuthenticatedUser

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

The following diagram illustrates the EMAIL2 CSP schema used in OMA DM.

The following diagram illustrates the EMAIL2 CSP 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.
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; 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; 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.
INSERVER
[Required] The name of the messaging service's incoming e-mail server.
KEEPMAX
[Optional] Specifies the maximum size (in Kilobytes) 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 CSP 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 CSP 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 email 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.

Elements	Available
parm-query	Yes
noparm	No
nocharacteristic	Yes
characteristic-query	Yes Recursive: Yes Root level of the Configuration Service Provider: No

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

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

Code Example

The following XML code example shows how to use the EMAIL2 Configuration Service Provider to configure an e-mail account.

<wap-provisioningdoc>
    <characteristic type="EMAIL2">
        <characteristic type="{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}">
            <parm name="SERVICENAME" value="Bobs Mail Account" />
            <parm name="SERVICETYPE" value="POP3" />
            <parm name="INSERVER" value="mail.northwindtraders.com" />
            <parm name="OUTSERVER" value="smtp.northwindtraders.com" />
            <parm name="NAME" value="Bob Kelly" />
            <parm name="REPLYADDR" value="bobk@northwindtraders.com" />
            <parm name="AUTHNAME" value="bobk" />
            <parm name="AUTHSECRET" value="bobs_password" />
            <parm name="DOMAIN" value="" />
            <characteristic type="NAMEDPROPS">
                <parm name="MyNamedProp#0003" value="1" />
                <parm name="AnotherNamedProp#0003" value="200" />
            </characteristic>
            <characteristic type="TAGPROPS">
                <parm name="8128000B" value="1"/>
                <parm name="812C000B" value="1"/>
            </characteristic>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Remarks

This Configuration Service Provider is managed over the OMA Client Provisioning (formerly WAP) and OMA DM protocols.

If you want to configure a Windows Mobile–based 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).