Key-value pairs for customization Email+ for iOS

key-value pairs for customization describes the key-value pairs available to administrators to customize Email+ for iOS app behavior. These key-value pairs define app behavior such as providing detailed notifications to device users and export contacts from Email+.

Key-value pairs marked as Ivanti EPMM only are not applicable to Ivanti Neurons for MDM. For Ivanti Neurons for MDM deployments, these key-value pairs are either provided as fields in Ivanti Neurons for MDM or are set automatically and do not require action from the administrator. See Email+ configuration field description (Ivanti Neurons for MDM) for a description of the fields in Ivanti Neurons for MDM.

Some values can use Ivanti EPMM variables, such as $EMAIL$. Ivanti EPMM substitutes the device user’s value when sending the app configuration to the device.

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

Table 3.  key-value pairs for customization

Key

Value: Enter/ Select one

Description

Required key-value pairs

email_address
(Ivanti EPMM only)

Email address of the device user

Typically, this field uses the Ivanti EPMM variable $EMAIL$.

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

email_device_id

(Ivanti EPMM only)

$DEVICE_UUID_NO_DASHES$

Identifies the device to the ActiveSync server.

Always use the Ivanti EPMM variable $DEVICE_UUID_NO_DASHES$.

email_exchange_host

(Ivanti EPMM only)

FQDN of the ActiveSync server or Standalone Sentry

The fully qualified domain name of the ActiveSync server. If you are using a Standalone Sentry, enter the fully qualified domain name (FQDN) of Standalone Sentry.

Example:

mySentry.mycompany.com

 

  • When using Standalone Sentry with Lotus Domino server 8.5.3.1 Upgrade Pack 1, set the server address to Standalone Sentry FQDN/traveler.
  • When using Standalone Sentry with a Lotus Domino server earlier than 8.5.3.1 Upgrade Pack 1, set the server address to Standalone Sentry FQDN/servlet/traveler.
  • If you are using an IBM Lotus Notes Traveler server without a Standalone Sentry, append the IBM Lotus Notes Traveler server FQDN to the host path of the IBM Lotus Traveler server. If you use a custom path, append the custom path to the FQDN.

email_exchange_username

(Ivanti EPMM only)

User ID for the ActiveSync server

The user ID for the ActiveSync server.

Typically, you use the Ivanti EPMM variable
$USERID$.

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

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

This KVP is case sensitive. Enter the key in lower case.

Background email check and user notifications

allow_detailed_notifications

(Ivanti EPMM only)

  • true
  • false

true: Device user sees detailed notifications. The details can include sensitive information such as email subject, or event titles and times.

false: Notifications do not include any details.

Default if key-value is not configured: false.

should_cache_tunneling_config

  • true
  • false

Use the key should_cache_tunnelling_config along with the key allow_device_keychain.

true: The configuration will be cached by AppConnect, as a result device user sees detailed push notifications and badge count (number of unread mails) after force closing the app.

false: The configuration is not cached.

Default if key-value is not configured: false.

Certificates

allow_certificate_revocation_check

  • true
  • false

true: Allows CRL check.

Default if key-value is not configured: false

allow_device_keychain

  • true
  • false

true: Email+ stores the decryption key received from the UEM client in the device keychain. This allows Email+ to access its credentials and check email when iOS launches it in the background, thus improving background email notifications.

false: The AppConnect content decryption key is not stored on the device.

Ivanti recommends that customers set this to true in conjunction with a strong device passcode. For more information see Background email checks and user notifications.

Default if key-value is not configured: false

email_login_certificate

(Ivanti EPMM only)

From the dropdown list

The device uses the certificate for authentication.

See the Ivanti EPMM Device Management Guide for your deivce platform for information on configuring Certificate Enrollment settings.

If the certificate is password-encoded, Ivanti EPMM automatically also sends another key, email_login_certificate_MI_CERT_PW, with the password as the certificate’s value.

This key is required if Sentry is configured to require certificates.

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

email_trust_all_certificates

(Ivanti EPMM only)

  • 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 key-value is not configured: false.

email_user_certificate_self_service

(Ivanti EPMM only)

From the dropdown list

Allows the administrator to distribute certificates to device users. Users can then upload the certificates manually to the Ivanti EPMM user portal.

email_certificate_X

where X is 1 through 10

From the dropdown list

You can designate up to ten certificate authority (CA) root certificates as trusted. Email+ imports the certificate into its keychain of trusted certificates, and trusts any certificates derived from the CA root certificate in its keychain.

Designating a CA root certificate as trusted is necessary for the following:

  • You have configured device authentication in Standalone Sentry to require a certificate whose certificate authority is not a trusted CA.

A common scenario for this case is if you are using 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 Ivanti EPMM Admin Portal.

  • You have configured certificates for encrypting or signing S/MIME emails and these certificates 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.

S/MIME

email_encryption_certificate

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 keychain and selects the new certificate as the encryption certificate. It leaves the previous certificate in the keychain.

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

For more information about configuring S/MIME for Email+ for iOS, see S/MIME support in Email+ for iOS.

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

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

email_signing_certificate

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 keychain and selects the new certificate as the signing certificate. It leaves the previous certificate in the keychain.

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

For more information about configuring S/MIME for Email+ for iOS, see S/MIME support in Email+ for iOS.

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

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

S/MIME- Support for Retired Certs

email_escrow_certificates

Each dictionary consists of the following two keys:

  • email_escrow_certificates
  • email_escrow_certificates_MI_CERT_PW

Use this option to use the multiple retired certificate for decrypting older messages. This value corresponding to this KVP is an array of dictionaries.

  • email_escrow_certificates: Is a base64 encoded p12 archive with certificate and private key.
  • email_escrow_certificates_MI_CERT_PW: Is a password string to unpack archives.

Manage contacts

allow_export_contacts
(Ivanti EPMM only)

  • true
  • false

true: Allows Email+ users to export Email+ contacts to an Email+ contacts group on the personal side of the device.

When device users export the contacts, they can 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.

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

Default if key-value is not configured: false.

limit_contact_export_to
(Ivanti EPMM only)

  • name_number
  • all
  • name_number: limits the exported contact information to each contact’s name and number.
  • all: exports all contact information for each contact.

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+ for iOS uses the value all.

Default if key-value is not configured: all

email_safe_domains

A comma-separated list of safe domains

Ensure that there are no spaces before or after the comma. A wildcard in the domain name is supported. The only format supported for domain names with a wildcard is *.domainname.com. Entering * only will make all domains safe.

Base domain is not included in the wildcard domain, it needs to be added explicitly if required. For example, *.domainname.com, domainname.com.

Email addresses not in the safe domain list are displayed in red color in Email+.

This configuration minimizes the risk that a user will accidentally send internal emails to external email addresses. You may want to use this key-value pair:

  • if your company policy requires this risk mitigation step.
  • if your company has multiple domains and you want to identify your company’s domains as opposed to domains that are not your company domains.

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

Default if key-value is not configured: Only the domain of the email account is safe.

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. For the alert to be displayed, the email_safe_domains key must also be configured.

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

Controls the maximum number of days for which emails are synced:

  • 0 = Download all emails.
  • 1 = Download emails received over the last day.
  • 2 = Download emails received over the last 3 days.
  • 3 = Download emails received over the last week.
  • 4 = Download emails received over the last 2 weeks.
  • 5 = Download emails received over the past month.

Default if key-value is not configured: 0

Device users can change the interval to a value less than the default maximum. This feature is useful for regulatory purposes, if an organization requires device users to have no more than n days of emails on their devices.

If the maximum email synchronization (email_max_sync_period) period is less than the default email synchronization period, then the maximum value is used.

email_default_sync_period

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

Controls the default time interval for which emails are downloaded:

  • 0 = Download all emails.
  • 1 = Download emails received over the last day.
  • 2 = Download emails received over the last 3 days.
  • 3 = Download emails received over the last week.
  • 4 = Download emails received over the last 2 weeks.
  • 5 = Download emails received over the past month.

Default if key-value is not configured: 2

Ivanti does not recommend setting the value as 0, as downloading all emails could take a very long time, and take up too much space on the device.

Maximum size for email

email_max_body_size

A number

Specifies the maximum size in megabytes permitted for each email that is received.

This feature allows administrators to manage bandwidth and memory consumption on devices by restricting the maximum size of individual emails.

If the size of the email is greater than the default or configured size, users are presented with the following message and the email cannot be downloaded: Email+ maximum message size exceeded.

Default if key-value is not configured: 4 MB.

Email attachments

email_max_attachment

A number

Specifies the maximum size in megabytes permitted for each email attachment for incoming emails. The key-value pair is applied to incoming emails only.

If you set the maximum value to 10MB, a device user who receives an email that includes attachments of 3MB, 9MB, and 10MB will be able to download each attachment. If, however, a device user receives an email with an 11MB attachment, the following alert is displayed and users cannot download the attached file: Failed To Retrieve Attachment Email+ maximum attachment size exceeded.

If users try to send an attachment larger than 10 MB, the following alert is presented: Warning: The message size exceeds 10 MB. Please confirm you would like to continue. Users have the option to either Cancel or Proceed. If users tap Proceed, the email is successfully sent.

This feature allows administrators to manage bandwidth and memory consumption on devices by restricting the maximum size of individual email attachments.

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

calendar_attachments

  • true
  • false

Enabled viewing of files attached to calendar meeting invites.This feature requires Exchange Web Services to be configured. Email+ fetches calendar attachments via an EWS API.

If Email+ is configured through Sentry, then

additional key-value pair email_ews_host is needed with server address.

The email_exchange_host is used automatically, but it is configured through Sentry email_ews_host.

Default if key-value is not configured: false

MI_SHARED_GROUP_ID

A unique, sufficiently complex alphanumeric string

Required to enable attaching of files from [email protected]

Ensure that the key-value pair is configured in the [email protected] configuration as well and that the value is identical (including case) in both Email+ and [email protected] configurations.

The key is case sensitive. Enter the key in upper case.

Configure mi_enable_doc_sharing with value true in the [email protected] configuration.

MI_AC_ACCESS_CONTROL_ID

A unique, sufficiently complex alphanumeric string

Required to enable attaching of files from [email protected]

Ensure that the key-value pair is configured in the [email protected] configuration as well and that the value is identical (including case) in both Email+ and [email protected] configurations.

The key is case sensitive. Enter the key in upper case.

Configure mi_enable_doc_sharing with value true in the [email protected] configuration.

Open links in a browser

Links in Email+ are opened by default in [email protected] If [email protected] is not installed on the device, Email+ for iOS displays an error. However, administrators can specify the default browser to use when device users click links in Email+.

Administrators can configure the default browser to be used for both HTTP and HTTPS links, using customized URL schemes. This allows finer control over the browser used to open HTTP and HTTPS links, respectively. Additionally, this key can be used to configure a customized browser as the one that launches when a device user clicks a link in Email+.

allow_safari_browser
(Ivanti EPMM only)

  • true
  • false

true: Allows Email+ to open URLs (included, for example, in an email) in Safari.

If the allow_safari_browser key is configured, the values of email_url_scheme_http and email_url_scheme_https are ignored.

Default if key-value is not configured: false.

email_url_scheme_http

  • mibrowser
  • googlechrome
  • firefox
  • microsoft-edge-http
  • touch-http
  • mibrowser: Opens links in [email protected] for iOS
  • googlechrome: Opens links in Chrome.
  • firefox: Opens links in Firefox
  • microsoft-edge-http: Opens links in Microsoft Edge
  • touch-http: Opens links in Opera.

Default if key-value is not configured: mibrowser

email_url_scheme_https

  • mibrowsers
  • googlechromes
  • firefox
  • microsoft-edge-https
  • touch-https
  • mibrowsers: Opens links in [email protected] for iOS.
  • googlechromes: Opens links in Chrome.
  • firefox: Opens links in Firefox
  • microsoft-edge-https: Opens links in Microsoft Edge
  • touch-https: Opens links in Opera.

Default if key-value is not configured: mibrowsers.

webatwork_install_link(Ivanti EPMM only. Not supported on Ivanti Neurons for MDM)

URL for [email protected]

If [email protected] is not installed on the device, device users are prompted to install [email protected] when they click on a webpage link in an email in Email+. If users accept the prompt, they are redirected to [email protected] for installing [email protected]

The [email protected] URL is available in the app catalog in the Ivanti EPMM Admin Portal. In Ivanti EPMM, go to Apps > App Catalog, click on the [email protected] app, and then click Global. In the global settings, for App URL, click Copy Link to Clipboard. Paste the link as the value.

Default signature

email_default_signature
(Ivanti EPMM only)

The default email signature

 

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

Default if key-value is not configured: Sent by Email+ for iOS managed by MobileIron

IBM Lotus Notes Traveler

email_enable_lotus
(Ivanti EPMM only)

  • true
  • false

Enter true only if your email server is IBM Lotus Notes Traveler.

Default if key-value is not configured: false

SSL

email_ssl_required
(Ivanti EPMM only)

  • 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 key-value is not configured: false

GAL search

gal_search_minimum_characters
(Ivanti EPMM only)

A number

The minimum number of characters Email+ uses for automatic Global Address List (GAL) lookup in Mail 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 key-value is not 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.

Classification Markers

email_security_classification_json

Is equal to JSON representation of JSON configuration.

Is equal to JSON representation of classification configuration.

For JSON. sample format. See, Classification markers section.

Allows the admin to configure Email Classification Markers, for secure sharing of Mail and Calendar events. The mail is marked with a marker that defines security of the mail. You can add any of the following markers to a mail:

  • Unofficial
  • Official
  • Secret
  • Protected
  • Top secret