Push notifications for Secure Mail

Secure Mail for iOS and Secure Mail for Android can receive notifications about email and calendar activity when the app is running in the background or is closed. Secure Mail for iOS supports notifications provided through Background App Refresh or push notifications provided through the Apple Push Notification service (APNs). Secure Mail for Android supports notifications provided through the Firebase Cloud Messaging service (FCM).

How push notifications work

Secure Mail sends push notifications for the following Inbox activities:

  • New mail, meeting requests, meeting cancellations, meeting updates: When APNs pushes notifications to an inbox, Secure Mail updates all folders, including Calendar, so that meeting changes are reflected immediately in users’ calendars.

  • For iOS, the Secure Mail status changes from read to unread and vice versa. The Secure Mail icon shows the total count of unread and new messages in the Exchange Inbox folder only. Secure Mail updates the icon after users read emails on a desktop or laptop computer.

    For iOS, Secure Mail still provides the count of unread Inbox emails for the sync period. If the Control locked screen notifications policy is On, push notifications appear on a locked device screen after iOS wakes up Secure Mail to perform a sync.

    During an installation or upgrade, Secure Mail for iOS prompts users to allow push notifications. Users can also allow push notifications later by using iOS Settings.

To provide push notifications for iOS and Android, Citrix hosts a listener service on Amazon Web Services (AWS) to perform the following functions:

  • Listen for Exchange Web Services (EWS) push notifications sent by Exchange Servers when there is Inbox activity. Exchange does not send any mail content to the Citrix service.

    No personally identifiable information is stored by the Citrix service. Instead, a device token and subscription ID identifies the specific device and Inbox folder to be updated within Secure Mail.

  • Send APNs notifications, containing only badge counts, to Secure Mail on iOS devices.

  • Send FCM notifications to Secure Mail on Android devices.

The Citrix listener service does not impact mail data traffic, which continues to flow between user devices and Exchange Servers through ActiveSync. The listener service, which is configured for high availability and disaster recovery, is available in three regions:

  • Americas
  • Europe, Middle East and Africa (EMEA)
  • Asia Pacific (APAC)

System requirements for push notifications

If your NetScaler Gateway configuration includes Secure Ticket Authority (STA) and split tunneling is off, NetScaler Gateway must allow traffic (when tunneled from Secure Mail) to the following Citrix listener service URLs:

Region URL IP Address
Americas https://us-east-1.pushreg.xm.citrix.com 52.7.65.6; 52.7.147.0
EMEA https://eu-west-1.pushreg.xm.citrix.com 54.154.200.233; 54.154.204.192
APAC https://ap-southeast-1.pushreg.xm.citrix.com 52.74.236.173; 52.74.25.245

Configuring Secure Mail for push notifications

To set up Apple Push Notifications or FCM for Secure Mail for app store distribution, in the Endpoint Management console, set Push notifications to ON and then select your region. The following figure shows the setting for iOS.

Image of push notification setting in Endpoint Management

For Android, the following figure shows the same Push notification setting as for iOS. In addtion, if the EWS is hosted in a different region from where the mail server resides, complete the EWS HostName setting. The default setting is empty. If you leave the setting empty, Endpoint Management uses the host name of the mail server.

Image of push notification setting for Android in Endpoint Management

Configure Exchange and NetScaler to allow traffic to flow to the listener service.

Exchange Server configuration

Allow outbound SSL (over port 443) from your firewall to the Citrix listener service URL for the region where your Exchange Server is located. For example:

Region URL IP Address
Americas https://us-east-1.mailboxlistener.xm.citrix.com 52.6.252.176; 52.4.180.132
EMEA https://eu-west-1.mailboxlistener.xm.citrix.com 54.77.174.172; 52.17.147.220
APAC https://ap-southeast-1.mailboxlistener.xm.citrix.com 52.74.231.240; 54.169.87.20

If you have a proxy server between Exchange Web Services (EWS) and the Citrix listener device, you can do one of the following.

  • Send EWS traffic through the proxy and then on to the listener device.
  • Bypass the proxy and route EWS traffic to the listener device directly.

To send EWS traffic through the proxy server, configure the EWS web.config file in the ClientAccess\exchweb\ews folder, as follows.

<configuration>
<system.net>
<defaultProxy>
<proxy usesystemdefault="false"
proxyaddress="http://proxy.example:8080"
bypassonlocal="true” />
</defaultProxy>
</system.net>
</configuration>`

For Exchange 2013 environments, you must add the system.net section to the web.config file manually. Otherwise, configurations described in this article should work for Exchange 2013. For troubleshooting, contact your Exchange administrator.

To bypass the proxy server, configure the bypass list to allow Exchange to make connections to the Citrix listener service.

When Secure Hub is enrolled with certificate-based authentication, you must also configure Exchange Server for certificate-based authentication. For details, see this Endpoint Management Advanced Concepts article.

NetScaler Gateway configuration

While the Exchange server needs to allow traffic to the listener service, NetScaler must allow traffic to the registration service. In this way, devices can connect to register for push notifications.

If your EWS and ActiveSync servers are different, configure your NetScaler traffic policy to allow EWS traffic.

Troubleshooting

To troubleshoot outbound connections, check the Exchange event logs, which include log entries when a subscription request or the notification for a subscription is invalid or fails. You can also run Wireshark traces on the Exchange Server to track outbound traffic to the Citrix listener service.

For other issues, try the Secure Mail Test Tool.

Secure Mail Push Notifications FAQs

When does iOS deliver notifications to Secure Mail?

If Secure Mail is running in the foreground, notifications are always delivered to Secure Mail. This is the only time that Citrix can guarantee that notifications are delivered. When Secure Mail enters the background, the application badge count always updates. However, notifications (lockscreen and banner notifications) rely on Background App Refresh and, particularly when iOS suspends or terminates the app, notifications are not a certainty. The following factors are outside the control of Citrix.

The following cases may affect the delivery of notifications:

  • The battery is low.
  • Secure Mail is not used frequently (rarely opened into the foreground).
  • Emails received outside of core usage times in which the app is suspended for an extended period in the background; for example, between midnight and 6 a.m.

Notifications are not delivered to Secure Mail in the following cases:

  • If the user closes Secure Mail, until the user manually reopens the app.
  • If the system has terminated Secure Mail. and the app has not been automatically restarted.
  • When Secure Mail is not active.

Important:

Notifications may not be delivered to Secure Mail when it is not active for many reasons, including but not limited to the following cases:

  • If the device is in Low Power Mode and Secure Mail is in the background. This is the most common case in which notifications are not delivered.
  • If Background App Refresh is off for Secure Mail and if Secure Mail is in the background. Note that users control this setting.
  • If the device has poor network connectivity. This situation depends entirely on the iOS device.

When Secure Mail does not receive a notification, Secure Mail does not sync new data to the device. As a consequence, the following situations occur:

  • Secure Mail syncs data only when users bring the app to the foreground.
  • Lockscreen notifications stop occurring for new mail. Calendar reminders still appear, however.

When does Android deliver notifications to Secure Mail?

In Android, notifications are always delivered to Secure Mail.

How does FCM affect email notifications that appear on the lock screen?

New mail notifications that appear on the device lock screen are generated based on data that is synced down to the device by Secure Mail. Importantly, this information does not come from the listener service.

To show new mail notifications, Secure Mail must be able to sync data from Exchange so that Secure Mail has the information available to create the notifications.

When you receive a new mail, the You have new messages FCM notification appears. Once the email sync completes in the background, the new mail appears in Secure Mail.

How does Background App Refresh affect Secure Mail and APNs?

If the user turns off Background App Refresh, the following situations occur:

  • Secure Mail does not receive notifications when Secure Mail is not the background app.
  • Secure Mail does not update the lockscreen with new email notifications.

Disabling Background App Refresh has a major effect on the behavior of Secure Mail. As stated earlier, badge updates based on APNs still occur, but no email is synced to the device in this mode.

How does Low Power Mode affect Secure Mail and APNs?

The behavior of the system with respect to Secure Mail is the same in Low Power Mode as it is when Background App Refresh is disabled. In Low Power Mode, the device does not wake up apps for periodic refresh and does not deliver notifications to apps in the background. The side effects are therefore the same as those listed in the Background App Refresh section above. Note that in Low Power Mode, badge updates still occur, based on APNs notifications.

How does APNs affect email notifications that appear on the lock screen?

New mail notifications that appear on the device lock screen are generated based on data that is synced down to the device by Secure Mail. Importantly, this information does not come from the listener service.

In order to show new mail notifications, Secure Mail needs to be able to sync data from Exchange so that Secure Mail has the information available to create the notifications.

If APNs notifications are not delivered to Secure Mail in the background, Secure Mail does not detect the notifications and hence does not sync new data. Because no new data is available to Secure Mail, no email notifications are generated on the device lockscreen, even when APNs notifications are not delivered.

What other issues can cause FCM-driven sync to fail in the background?

Various issues can cause FCM-driven sync requests to fail, including the following:

  • An invalid STA ticket.
  • When Secure Mail is woken in the doze mode, the app has 10 seconds to sync all data from the server.

If any of the preceding conditions occurs, Secure Mail cannot sync data. As a result, lockscreen notifications do not appear.

What other issues can cause APNs-driven sync to fail in the background?

A number of issues can cause APNs-driven sync requests to fail, including the following:

  • An invalid STA ticket.
  • A slow network connection. When Secure Mail is woken in the background, the app has 30 seconds to sync all data from the server.
  • If the data protection policy is enabled and Secure Mail is woken by an APNs notification, when the device is locked, Secure Mail cannot access the data store and sync does not occur. Note that this is only the case in which the system is attempting to cold start Secure Mail. If a user has already started Secure Mail at some point after unlocking the device, APNs-driven sync succeeds even when the device is locked.

If any of the preceding conditions occur, Secure Mail cannot sync data and hence cannot display locksscreen notifications.

How else does Secure Mail generate lockscreen notifications when notifications are not delivered or APNs is not in use?

If APNs is disabled, Secure Mail is still woken by periodic Background App Refresh events from iOS, assuming that Background App Refresh is enabled and assuming that Low Power Mode is off.

During these wakeup events, Secure Mail syncs new email from the Exchange Server. This new email can then be used to generate email notifications on the lock screen. Thus, even when APNs notifications are not delivered or APNs is disabled, Secure Mail can sync data in the background.

It’s important to note that this will occur less in real time than when APNs is in use and when APNs notifications are delivered to Secure Mail. When iOS routes APNs notifications to Secure Mail, the app immediately syncs data from the server and the lockscreen notifications appear to be real time.

In the event that Background App Refresh wakeups are required, lockscreen notifications do not occur in real time. In this case, Secure Mail is woken up at a frequency that iOS completely determines. As such, some time may elapse between when an email arrives in a user’s Inbox on Exchange and Secure Mail syncs that message and generates the lockscreen notification.

Also note that Secure Mail receives these periodic wakeups even when APNs is in use. In all cases in which Background App Refresh wakes up Secure Mail, Secure Mail attempts to sync data from Exchange.

How does Secure Mail differ from other apps that show content on the lock screen?

A very important difference - and one that leads to confusion - is that Secure Mail does not always show new email in real time on the lock screen in the same way that Gmail, Microsoft Outlook, and other apps do. The primary reason for this difference is security. To align with the behavior of the other apps, the Citrix listener service would require the user credentials to authenticate with Exchange to get the email content and also pass this email content through the Citrix listener service, as well as the Apple APNs service. The approach by Citrix to APNs notifications does not require the Citrix listener service to acquire or store the users’ password. The listener service has no access to the users’ mailbox or password.

A note about the native iOS mail app: iOS allows its own email app to maintain a persistent connection with the mail server, which ensures that notifications are always delivered. Third-party apps outside of the native mail are not allowed this capability.

Gmail app behavior: Google owns and controls both the Gmail app and the Gmail server. This means that Google can read message content and include that message content in the APNs notification payload. When iOS receives this APNs notification from Gmail, iOS does the following:

  • Sets the application badge to the value that is specified in the notification payload.
  • Displays the lockscreen notification using the message text that is contained in the notification payload.

This is a critical difference: It is iOS, not the Gmail app, that displays the lockscreen notification, based on the data contained in the payload. In fact, iOS may never wake the Gmail app, similar to the way that iOS may not wake Secure Mail when a notification arrives. However, because the payload contains the message snippet, iOS can display the lockscreen notification without any mail data having to be synced to the device.

In Secure Mail, this situation is different. Secure Mail must first sync message data from Exchange before the app can show the lockscreen notification.

Outlook for iOS app behavior: Microsoft controls Outlook for iOS. The organization to which the user belongs, however, controls the Exchange Servers from which data is obtained. Despite this setup, Outlook can display lockscreen notifications based on data that Microsoft provides in the APNs notification, because Outlook for iOS makes use of a model in which Microsoft stores user credentials. Microsoft then directly accesses the user’s mailbox from its cloud service and determines the existence of new mail.

If new mail is available, the Microsoft cloud service generates an APNs notification that contains the new mail data. This model operates in a similar way to the Gmail model, in which iOS simply takes the data and generates a lockscreen notification based on that data. The Outlook iOS app is not involved in the process.

Important security note on Outlook for iOS: There are clear security implications in the Outlook for iOS approach. Organizations need to trust Microsoft with passwords for their users so that Microsoft can access the user’s mailbox, which poses a security risk. For more information about the way Microsoft manages user’s passwords, see Microsoft TechNet.

For more FAQs specific to administrators on push notifications, see this Support Knowledge Center article. For more user-specific FAQs, see this Support Knowledge Center article.