Troubleshooting Outbound Connections
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.
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 – in particular 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 note: 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.
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 enabled. 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 of this article. Note that in Low Power Mode, the system continues to badge the app 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 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 this Microsoft Technet article.