NEW ARTICLE: How to configure push folders

[kewisch]

There is an in-product link that points to https://forum.k9mail.app/t/how-to-configure-push/1102 via https://k9mail.app/go/push-info . We should:

• Create a new article on SUMO for this, which might require checking how things work these days given @cketti is removing some push folder settings
• Be mindful that "push" has certain connotations, e.g. push notifications, which is different
• Update this to a mzla.link
• Send a PR to thunderbird-android to replace the in-product link

[monica-thunderbird]

Given how often this question comes up, I will likely link this resource to the announcement blog.

[cketti]

Note: We've recently changed the way push is configured. The FAQ entry is currently out of date.

[monica-thunderbird]

If it's not possible to write this article before the stable release, would it be advisable to have a brief description in the Getting Started article? ( See: NEW ARTICLE: Getting Started with Thunderbird for Android #6 )

[cketti]

Some information about "push" in Thunderbird for Android. Feel free to use as little or as much of it as you wish.

"Push notifications" in other apps usually work by some server in the cloud listening for some event and then notifying the device via Firebase Cloud Messaging (FCM, i.e. Google's Android push mechanism). That will wake up the app that then maybe fetches some additional data to display a notification. While this approach is very battery friendly, for an email client it would require sending account credentials to some server in the cloud so it can connect to the user's mail server to listen for new messages. It also requires Google Play Services to be installed on a device. This is NOT how our apps work. Instead the app directly connects to the mail server and keeps the connection open to be notified when anything on the server changes. This only works for IMAP accounts and only with servers that support the IDLE extension (but it's very rare that a server doesn't support this extension).

Because we're using this approach, we need to do things that other apps that support "push notifications" don't have to do.

• We need to run a so called foreground service to be able to keep a connection to the mail server open. Using a foreground service requires an app to display an ongoing notification (so the user is aware there's an app running that consumes system resource). This notification has to be shown by default. But users can minimize or even disable/hide this notification without that impacting the operation of the app. The "push info" screen (see screenshot below) contains more information and direct access to the relevant system settings screen.
• Since Android 13 users also have to grant the app the special "alarms & reminders" permission. This is necessary to "refresh" the open connection to the mail server. This is necessary so the connection is not automatically terminated by either the mail server or the internet provider.

Push is enabled on a per-folder basis. To do so, go to Manage folder → [Folder name] and enable the Enable Push setting. Note: The Enable sync setting is for periodic syncs and can be disabled once push is enabled.

Once Push is enabled for at least one folder the foreground service should be started and the notification should be shown in Android system bar (the bell icon, see screenshot below). Side note: We currently seem to have a bug that prevents the foreground service from starting right after an account has been set up. Stopping the app and starting it again, fixes that. I'm working on fixing that bug.

On Android 13 and above, the notification will let users know they need to grant the "Alarms & reminders" permission. They can get to the relevant screen by tapping the notification.

Once the permission was granted (or right after enabling push on older Android versions), the notification should look like this:

Tapping the notification opens the "push info" screen with more information.

Tapping the Configure notification button will open the relevant Android settings screen to configure the ongoing notification. Minimizing the notification will hide the bell icon from the status bar, but still keep the notification in the notification shade. That way the status of the push connections can be seen ("Waiting for new emails" or "Sleeping until network is available").

But the notification can also be hidden without that impacting the operation of the foreground service. Notifications for new messages use a separate notification category and are configured independently. Users can get to that screen via Settings → [Account] → Notifications → Notification categories → Messages.

[cketti]

Addendum: With IMAP IDLE we need to open one connection per folder that has push enabled. Most providers have rather low connection limits. So users need to be very selective about for which folders they enable push. Additionally, we currently limit the number of push connections to the value configured under Settings → [Account] → Fetching mail → Advanced → Max folders to check with push. However, we currently don't notify the user when that limit is reached or prevent them from enabling push for additional folders. The app will silently only enable push for the first X folders (with undefined order, so really X random folders). Obviously, that's not great and something we'll improve in the future. But probably something we need to point out in a trouble shooting section.

[rtanglao]

• revision 288510: first draft without screenshots, do not approve please :-)
• revision 288511: add screenshots, needs philipp and wayne's approval

[rtanglao]

• @cketti @wsmwk @kewisch please suggest edits for https://support.mozilla.org/en-US/kb/configure-push-email-thunderbird-android/revision/288511

[cketti]

Feedback for revision 288511:

Thunderbird does not enforce this limit. Please ensure you do not go over this limit.

To me this sounds like the limit is merely a suggestion. However, the app does enforce this limit. What the app doesn't do is tell you which of the folders configured for push are actually checked using push. Maybe change to something like this:

Thunderbird doesn't warn when this limit is exceeded. Exceeding this limit means some folders configured for push won't be checked using push.

---

Once you enable push mail, Thunderbird for Android will display a notification. You change this notification (e.g. turn it off or change the display) by tapping on the notification or via app menu ≡ > Settings gear icon gear icon > Notifications > Messages under Notification categories

The "or via app menu ≡ > Settings gear icon gear icon > Notifications > Messages under Notification categories" part is not correct. That will configure notifications for new messages, not the "push service" notification. I think we can just drop that part of the sentence.

---

If you choose to display the push mail notification, Android offers several display options. Here are the most important:

• Default: ring or vibrate depending on your Android settings or Silent.
• Sound: the default notification sound.
• Show notification dot: whether or not to display a notification dot in the Android system bar.

None of these feel particularly relevant for this case. Remember, this is only the notification that signals the state of the push service. Notifications for new messages are configured separately.

Maybe we need some text to make it clear that the "push service" notification is completely separate from notifications for new messages.

[rtanglao]

• revision 288695:
  • Thunderbird doesn't warn when this limit is exceeded. Exceeding this limit means some folders configured for push won't be checked using push.
  • The "or via app menu ≡ > Settings gear icon gear icon > Notifications > Messages under Notification categories" part is not correct. That will configure notifications for new messages, not the "push service" notification. I think we can just drop that part of the sentence.
  • None of these feel particularly relevant for this case. Remember, this is only the notification that signals the state of the push service. Notifications for new messages are configured separately. Maybe we need some text to make it clear that the "push service" notification is completely separate from notifications for new messages. <- I have renamed the section to Control the Push mail service notification
  • Added section Where are the notifications for new emails configured?
  • revision 288703:
    • fix typos
    • rename sections to make them clearer
    • collapse sections that are probably rarely used

[cketti]

Once push email is enabled for at least one folder, you should see a bell icon in the Android system bar. The bell icon indicates that push email is enabled and working.

Maybe drop "and working". The bell icon will also be displayed if e.g. the permission is missing or there's no network connectivity.

If you do not see the bell icon, please stop Thunderbird for Android and open it again.

FYI: I recently fixed this bug. We should be able to remove this sentence once 8.2 is released.

Otherwise LGTM :+1: