Key-value pairs for Email+ (Android AppConnect)

Key-value pairs for configuring Email+ for Android AppConnect app behavior describes the key-value pairs available to administrators to customize Email+ app behavior on Android devices. These key-value pairs define app behavior such as providing detailed notifications to device users and exporting contacts from Email+.

Key-value pairs marked as Core only are not applicable to Cloud. For Cloud deployments, these variables are either provided as fields in Cloud or are set automatically and do not require action from the administrator. See Configuring Email+ for Android AppConnect in Cloud for a description of the fields in Cloud.

  • Some values can use the UEM variables, such as $EMAIL$ for Core and ${userEmailAddress} for Cloud. The UEM substitutes the device user’s value when sending the app configuration to the device.
  • If you make a mistake in configuring the required key-value pairs, the app displays a message to the device user that the configuration has an error, and to contact the administrator.

You can configure and customize the following features with key-value pairs:

Table 5.  Key-value pairs for configuring Email+ for Android AppConnect app behavior

Key

Value: Enter/Select one

Description

Required Key-value pairs to configure an account on Email+

email_address

Email address of the device user

To validate that the account signed in is indeed the corporate account (the value is automatically set into modern auth UI, but can be changed there)

Core

Typically, this field uses the Core variable $EMAIL$.

You can also use combinations of these Core variables, depending on your ActiveSync server requirements:
$USERID$, $USER_CUSTOM1$,
$USER_CUSTOM2$, $USER_CUSTOM3$, $USER_CUSTOM4$.

Cloud

Typically, this field uses the Cloud variable ${userEmailAddress}.

You can also use combinations of the user attribute variables, depending on your ActiveSync server requirements. The user attribute variables are listed in Cloud in Admin > Attributes.

email_device_id

The device ID that the ActiveSync server uses for the device.

Core

Always use the Core variable $DEVICE_UUID_NO_DASHES$.

Cloud

Always use the Cloud variable ${deviceSN}.

email_exchange_host

FQDN of the ActiveSync server or Standalone Sentry

The fully qualified domain name (FQDN) of the ActiveSync server or Standalone Sentry.

This KVP should be set to outlook.office365.com.

Example: mySentry.mycompany.com

email_exchange_username

User ID for the ActiveSync server

Core

Typically, you use the Core variable
$USERID$.

If your ActiveSync server requires a domain, use <domain name>\$USERID$. For example: mydomain\$USERID$.

You can also use combinations of these Core variables, depending on your ActiveSync server requirements: $EMAIL$,
$USER_CUSTOM1$, $USER_CUSTOM2$, $USER_CUSTOM3$, $USER_CUSTOM4$.

Cloud

Typically, you use ${userEmailAddressLocalPart}.

If your ActiveSync server requires a domain, use
<domain name>\${userEmailAddressLocalPart}.
Example: mydomain\${userEmailAddressLocalPart}.

Depending on your ActiveSync server requirements, you can use ${userEmailAddress}

Background email check and user notifications

allow_detailed_notifications
  • true
  • false

true: Device users see detailed notifications. The details can include sensitive information such as email subject and body previews, or event titles and times.

false: Device users see normal notifications.

Default if no key-value is configured: false.

Certificates

The necessary certificate setting must have been created in the UEM.

email_login_certificate

The certificate setting from the dropdown list

The UEM sends the contents of the certificate as the value.

Is also used when CBA is configured (to check if supported by Android)

If the certificate is password-encoded, Core automatically sends another key-value pair. The key’s name is the following string:

<name of key for certificate>_MI_CERT_PW

The value is the certificate’s password.

Default if no key-value is configured: Certificates are not used.

email_trust_all_certificates
  • true
  • false

true: Email+ automatically accepts untrusted certificates. Typically, you enter true only when working in a test environment.

false: Email+ does not accept untrusted certificates.

Default if no key-value is configured: false.

email_certificate_X,
where X is 1 through 10

The certificate setting from the dropdown list

Email+ imports the certificate into its keystore of trusted certificates, and trusts any certificates derived from the CA root certificate in its keystore. The certificate must be DER-encoded. You can add up to ten certificate authority (CA) root certificates.

Reasons for designating a CA root certificate as trusted:

  • Standalone Sentry requires a certificate, whose certificate authority is not in the Email+ keychain, for device authentication. A common scenario is if Standalone Sentry uses a self-signed certificate or a certificate that is not derived from a well-known certificate authority.

You specify this certificate to Email+ in the key email_login_certificate. It corresponds to the certificate you specified for device authentication in Standalone Sentry configuration in the Core Admin Portal.

  • Certificates configured for encrypting or signing S/MIME emails are self-signed or not derived from a well-known certificate authority.

You specify these certificates in the keys email_encryption_certificate and email_signing_certificate.

Use .DER format instead of normal .PEM format for email_certificate_X certificates.

The trusted CA root certificate is listed in Email+ in Settings > Advanced Settings > KeyStore.

eas_min_allowed_auth_mode
  • basic
  • cert_base
  • modern_auth

Defines the authentication method to the Exchange ActiveSync server.

  • basic: Uses user name and password.
  • cert_base: Uses identity certificates for certificate-based authentication.
  • modern_auth:Uses enable modern auth for corresponding protocol. Enables Oauth 2.0 authorization.

Modern Auth Authority URL and Modern Auth Resource URL: when configured through sentry uses the following values:

  • modern_auth_authority_url: https://<SentryHostname>/proxyservice
  • modern_auth_resource_url: https://<SentryHostname>

For certificate-based authentication, the key email_login_certificate must also be configured.

Default if no key-value is configured: basic.

allow_certificate_revocation_check
  • true
  • false

The admin can use this KVP to check certificates validity. The CRL check for server certificate is performed only if th email_trust_ all_ certificates KVP is set to "false".

S/MIME

email_encryption_certificate

The certificate setting from the dropdown list

Specifies the certificate to use for encrypting S/MIME emails.

The UEM sends the contents of the certificate as the value.

Email+ imports the key into the keystore and selects the certificate as the encryption certificate.

If you change the certificate, Email+ imports the new certificate into the keystore and selects the new certificate as the encryption certificate. It leaves the previous certificate in the keystore.

If you delete the key-value pair, Email+ leaves the certificate in the keystore. It changes its settings to specify that no certificate is selected as the encryption certificate.

Using the Email+ user interface, the device user can:

  • change the encryption certificate by manually importing one and selecting it for use.
  • encrypt all emails with the certificate or encrypt a specific email with the certificate.

Email+ automatically encrypts emails if the emails in the thread are encrypted.

For more information about configuring S/MIME for Email+, see S/MIME support in Email+ for Android for identity and encryption.

Default if no key-value is configured: Certificate is not configured.

For S/MIME certificates use .DER format instead of normal .PEM format.

email_signing_certificate

The certificate setting from the dropdown list

Specifies the certificate to use for signing S/MIME emails.

The UEM sends the contents of the certificate as the value.

Email+ imports the key into the keychain and selects the certificate as the signing certificate.

If you change the certificate, Email+ imports the new certificate into the keystore and selects the new certificate as the signing certificate. It leaves the previous certificate in the keystore.

If you delete the key-value pair, Email+ leaves the certificate in the keystore and changes its settings to specify that no certificate is selected as the signing certificate.

Using the Email+ user interface, the device user can:

  • change the signing certificate by manually importing one and selecting it for use.
  • sign all emails with the certificate or sign a specific email with the certificate.

For more information about configuring S/MIME for Email+, see S/MIME support in Email+ for Android for identity and encryption.

Default if no key-value is configured: Certificate is not configured.

email_signing_digest
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512

Configures signature algorithm. The default value is set to SHA-1.

The restriction is empty by default. If there is no value or invalid value set, then SHA-1 is used.

Manage contacts

allow_export_contacts
  • true
  • false

true: Allows Email+ users to export the Email+ contacts outside of the AppConnect container to the native contacts app. Device users can select the “Sync to personal profile” option, in the settings of the Email+ Contacts app, to export the contacts.

Exporting contacts allows users to see the caller ID of incoming calls from phone numbers in the list of corporate contacts. Third-party apps can also access the corporate contacts. If contacts are not exported, users see the caller ID only for personal contacts.

false: Device users cannot export the Email+ contacts. They see the caller ID only for personal contacts.

When the device is retired or Email+ is retired, the corporate contacts are removed from both Email+ and the native contacts app.

Default if no key-value is configured: true.

allow_export_contacts_to_email
  • true
  • false

true: Device users have the option to export contacts as an attachment to an outgoing email. The attachment is an unencrypted VCF (Virtual Contact File) file.

false: Device users do not have the option to export contacts as an attachment to an outgoing email.

Default if no key-value is configured: true.

allow_export_contacts_to_sdcard
  • true
  • false

true: Device users have the option to export the contacts to the SD card.

If the device user chooses the option, Email+ exports the contacts as an encrypted VCF (Virtual Contact File) file. The encrypted VCF file is readable only by Email+ and other secure apps.

false: Device users do not have the option to export contacts to the SD card.

Default if no key-value is configured: true.

limit_contact_export_to
  • name_number
  • all

name_number: Limits the exported contact information to each contact’s name and number information. Use this setting to minimize the exposure of corporate data.

all: Exports all the contact information.

This field is used only if allow_export_contacts is set to true.

If you enter a value other than all or name_number, Email+ uses the value all.

Default if no key-value is configured: all.

email_safe_domains

comma-separated list of safe domains

Ensure that there are no spaces before or after the comma.

Email addresses not in the safe domain list are displayed in red color when composing new emails or creating new calendar invitations in Email+.

You may want to use this key-value pair if you company has multiple domains and you want to identify the company domains as opposed to domains that are not company domains.

To disable this feature, you can set the value to "*"

Example:
mycompany.com,mycompany.net,internal.mycompany.com

Default if no key-value is configured: Only the domain of the user's email address is considered safe. All other domains will be highlighted in red.

email_alert_unsafe_domains

 
  • true
  • false

true: Users see an alert if the recipients in an email or calendar invite include addresses that are not in a safe domain.

If the key is configured but safe domains are not configured, only the domain of the user's email address is considered safe. Device users have the option to either proceed or cancel sending the email.

false: An alert is not displayed for addresses not in a safe domain.

Default if key-value is not configured: false.

Syncing

email_max_sync_period
  • 0
  • 1
  • 2
  • 3
  • 4
  • 5

Specifies the maximum sync period for which emails are downloaded:

0: all emails.

1: emails received over the last one day.

2: emails received over the last three days.

3: emails received over the last seven days.

4: emails received over the last two weeks.

5: emails received over the last one month.

Default if no key-value is configured: 0.

email_default_sync_period
  • 0
  • 1
  • 2
  • 3
  • 4
  • 5

Specifies the default period for which emails are downloaded.

1: emails received over the last one day.

2: emails received over the last three days.

3: emails received over the last seven days.

4: emails received over the last two weeks.

5: emails received over the last one month.

If configured, all options will be available in Email+. Device users can change the default value. If email_max_sync_period is also configured, options greater than sync period specified in email_max_sync_period will not be available on the device.

Default if no key-value is configured: 2.

Additionally, the default value is used in the following cases:

  • If the value is not 1,2,3,4, or 5.
  • The value is larger than the value for email_max_sync_period.

After an upgrade, the app retains the default sync period set by the device user.

Maximum size for email attachments

email_max_attachment

A number

Specifies the maximum size in megabytes of an email that Email+ will send without a warning to the device user. The maximum size includes the body of the email plus its attachments.

Allowed values are integers starting with 1.

If the Exchange server has an email size limit that is less than the limit specified in email_max_attachment, the Exchange server does not deliver the email.

Default if no key-value is configured: 10 MB.

Maximum size for email attachments

email_max_body_size

A number

Specifies the maximum limit for email message body size that can be received by the Email+ app.

Default: 4 MB

Default signature

email_default_signature

The default email signature

The value of this key is the default email signature for all emails. However, the device user can override the default email signature at any time. After the user defines the default email signature, Email+ does not use the value in the key, even if you update it.

Default if no key-value is configured: Sent by Email+.

SSL

email_ssl_required
  • true
  • false

true: Secures communication using HTTPS to the server specified in email_exchange_host. Typically, set this field to true unless you are working in a test environment.

Default if no key-value is configured: true.

GAL search

gal_search_minimum_characters

A number

The minimum number of characters Email+ uses for automatic Global Address List (GAL) lookup in Mail, Calendar, and Contacts.

When device users enter the specified number of characters of a name, Email+ searches the GAL, and presents the matches that it finds.

On your Exchange server, set the minimum number of characters for GAL search to the same value you set for this key. If you do not, GAL search will not work properly in Email+.

Default if no key-value is configured: 4.

gal_search_display_name
  • true
  • false

true: Enables Display Name in Email+ Settings > Contacts by default.

false: Disables Display Name in Email+ Settings > Contacts by default.

Default if key-value is not configured: true

contacts_display_order
  • first_last
  • last_first

Sets the default display order for contact names in search results. Device users can change the display order in Email+ in Settings > Contacts.

The values are case sensitive; enter in lower case.

first_last: Contact names in search results are displayed with first name followed by the last name.

last_first: Contact names in search results are displayed with last name followed by the first name.

Default if key-value is not configured: first_last.

Prompt the device user for password

prompt_email_password
  • true
  • false

true: Email+ prompts the user for the email password before attempting to connect to the email server.

false: When Email+ first launches and connects to the email server, Email+ provides the password set in the Email+ configuration to the server. If a password is not configured, an empty string is provided to the server. In this case, after the connection is established, Email+ prompts the user for a password. If the email server limits the number of password attempts, the server counts the first connection as one failed attempt.

Set the value of this key to true if the email server allows only a small number of password attempts. Example: If the email server allows only three attempts, setting this value to true ensures that device users get three attempts, not two attempts.

Kerberos-based authentication is designed to work without user passwords. Since setting prompt_email_password to true always prompts the user for a password, be sure the value is false (the default) if using Kerberos-based authentication.

Default if no key-value is configured: false.

email_password

User’s password for the ActiveSync server

If configured, Email+ does not prompt users for a password.

Delete this key if you want the device user to enter the password when using Email+. Ivantirecommends deleting the key.

Core

You can use the Core variable $PASSWORD$ if you have checked Save User Password in Settings > Users&Devices > Registration. Core then passes the user’s password as the value to the device.

If you plan to use the $PASSWORD$ variable, be sure to set Save User Password to Yes before any device users register. If a device user was registered before you set Save User Password, Email+ prompts the user to enter the password manually.

For Google accounts, as part of a larger setup for synchronizing Google account data, you can use $GOOGLE_AUTOGEN_PASSWORD$. For more information, see “Synchronizing Google account data” section in the Core Device Management Guide for your device platform.

Default if no key-value is configured: Email+ requests device users to enter the password.

Dialing

show_dialing_confirmation
  • true
  • false

true: Users see a confirmation dialog when they tap on a phone number in an email. Tapping on the phone number in the dialog, dials the phone number. Tapping the back arrow cancels the call.

false: Users do not see a confirmation dialog. When a user taps on a phone number in Email+, the number is automatically dialed.

Default if no key-value is configured: false.

Show pictures

show_pictures_default
  • true
  • false

true: Enables the Show Pictures option. Device users automatically see images when opening an email.

false: Disables the Show Pictures option. Device users must tap Show Pictures to view images when opening an email.

Device users can override the value you configure by turning the Show Pictures option on or off.

If you change the key’s value, Email+ does not change the Show Pictures option until Email+ does a full synchronization. A full synchronization occurs only when you change certain fundamental key-value pairs like email_address, or when the device user uninstalls and reinstalls Email+.

Default if no key-value is configured: false.

Default network timeout

default_network_timeout

A positive integer

 

The value is represented in seconds.

The value overwrites the default connection timeout value for all requests. You may want to configure the key-value pair to manage slow connections with the ActiveSync server or for syncing large folders and emails.

If the value is 0, negative, or non-integer, the default value is used.

Default if no key-value is configured: 90 seconds.

Troubleshooting

disable_analytics
  • true
  • false

true: Disables sending Email+ analytics.

false: Enables sending Email+ analytics.

Default if no key-value is configured: False.

allow_logging
  • true
  • false

true: Email+ logs data in the Android logging system.This is useful for problem diagnosis.

Typically, you enter true only when working in a test environment. Otherwise, enter false.

Default if no key-value is configured: false.

enabled_features
  • export_contacts
  • skip_empty_links
  • show_formatting
  • block_external_gal
  • lotus
  • rms_support
  • multiple_accounts
  • richtext_event_support
  • allow_shortcuts
  • eas_16
  • calendar_delegation

export_contacts: If allow_export_contacts key-value pair is set to true and export_contacts value is added to the keyvalue pair then Email+ contacts will be automatically synced to native Contacts app.

skip_empty_links: Some exchange servers block custom links and the hyperlinks are stripped from the email body. For example, the url mibrowser:// that is used to launch Web@Work and may not become click-able when sent via email.

The work around for this problem is, Email+ has additional capability to detect such emails and automatically fetch their body as MIME ata that is unmodified by exchange.

We recommend that administrators evaluate this capability in their environment by adding "skip_empty_links" into the "enabled_features" KVP. Fetching MIME data may not work in all configurations.

show_formatting: Enables the “Always show formatting” option if it was not previously changed manually.

block_external_gal: Disables contacts search through Email+ contacts for external applications.

lotus: Enables Lotus server support

rms_support: Enables fetching, displaying and composing of the protected messages.

multiple_accounts: Enables secondary email account on the same device.

richtext_event_support: Enables the user to fetch an event note's content in HTML format and then edit it using rich text editor. Disabled by default.

allow_shortcuts: Enables the user to create shortcuts for Calendar, Contacts, Tasks, and Notes.

eas_16: Enables ActiveSync 16 specific folder synchronization features in Email+. When Email+ receives "eas_16" the first time, Folder resync is expected.

When "eas_16" protocol is added to enabled_features KVP:

    • if the highest ActiveSync version for the server is 16.1 or higher, enable Email+ to sync via EAS 16.1 version.
    • if the highest ActiveSync version for the server is 16.0, enable Email+ to sync via EAS 16.0 version
    • if the highest ActiveSync version for the server is lower than 16.0, then it works as per the current settings.

calendar_delegation: Enables the Add Delegated Calendar option.

disabled_features
  • save_attachment
  • print
  • show_snippet
  • personal_events
  • crl_signature_check

save_attachment: Disables the save attachments option. When this option is added the “Save As” button is not available for email attachments. Attachments can still be opened and viewed in Docs@Work or mail application.

print: Disables the ability to print a message.

show_snippet: This option removes "Text preview" setting and disables message preview displaying. If this option is enabled the user can set the number of lines visible for message preview, through Email+ app Settings on the mobile device.
By default the number of lines set for preview is set to two.

personal_events:Adding 'personal_events' value to 'disabled_features' KVP removes "Overlay personal events" in Settings by admin.

When 'personal_events' value is removed from 'disabled_features', the "Overlay personal events" appears in Settings and has previous state that user had applied.

crl_signature_check: Disables CRL check for the email signature certificates.

Microsoft Office 365 authority and resource URL

modern_auth_authority_url

https://login.microsoftonline.com/common

This KVP is added to specify Microsoft Office 365 authority url.

modern_auth_resource_url

https://outlook.office365.com

This KVP is added to specify Microsoft Office 365 resource url.

Document classification capabilities

email_security_classification_json

Default value for this key is empty.

Enables the email classification feature. If present, it specifies the list of classification values to be used and all the supported permutations. See Document classification capabilities section for more information.

Report phishing

report_phishing_address

email address

Enabling 'Report Phishing' option onView screen in the "More" menu. Phishing email is sent to email address set in value.

Mail organization

organize_by_date
  • true
  • false

Disables email treading for email messages.

false: "Email Threading” is turned "ON".

Calendar week view

show_week_number
  • true
  • false

Displays the week number in the week and month view for Calendar. You can enable or disable week number view from device Settings.

Default if no key-value is configured: true

Setup access to Exchange server via EWS protocol

email_ews_host

 FQDN of the EWS server

To support EWS authentication when email_exchange_host KVP does not contain a fully qualified domain name (FDQN) of the EWS server, email_ews_host KVP should be added and have a FDQN as the value for the EWS server.

If not configured, the value of email_exchange_host KVP is used as the EWS server by Email+.

ews_min_allowed_auth_mode
  • basic
  • modern_auth

Defines the authentication method for the Exchange server through EWS protocol. Supported authentication methods are:

  • basic authentication: Uses username and password.

  • modern authentication: Uses enable modern auth for corresponding protocol. Enables Oauth 2.0 authentication.