Difference between revisions of "AppSuite:OX Mail App"

(Setup App Notifications)
 
(36 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= OX Mail v2 =
+
= OX Mail =
  
The OX Mail v2 is a companion app for OX App Suite, and brings the power of OX App Suite web-based email to your customers' mobile devices. The OX Mail v2 is a native app designed specifically for Android and iOS smartphones and tablets.
+
The OX Mail is a companion app for OX App Suite, and brings the power of OX App Suite web-based email to your customers' mobile devices. The OX Mail is a native app designed specifically for Android and iOS smartphones and tablets.
  
With a focus on security and user-experience, OX Mail v2 serves all your email needs on the go. Most notably you can answer and process mails even when you are offline, mails are synced when you go online. For completing addresses, OX Mail v2 uses the address book of the device along with all received and sent mails. When you have deleted an email by accident, you can easily undo that. Furthermore OX Mail v2 provides a list of known features such as pushing new emails onto your device, supporting mail folders, handling attachments, showing the number of unread email, and so on.
+
With a focus on security and user-experience, OX Mail serves all your email needs on the go. Most notably you can answer and process mails even when you are offline, mails are synced when you go online. For completing addresses, OX Mail uses the address book of the device along with all received and sent mails. When you have deleted an email by accident, you can easily undo that. Furthermore OX Mail provides a list of known features such as pushing new emails onto your device, supporting mail folders, handling attachments, showing the number of unread email, and so on.
  
 
== Key Benefits ==
 
== Key Benefits ==
  
* Additional privacy and integration with Dovecot Anti-Abuse Shield
+
* Additional privacy and integration with OX Abuse Shield
 
* Offline availability
 
* Offline availability
 
* Branding for customized design
 
* Branding for customized design
Line 19: Line 19:
 
== Requirements ==
 
== Requirements ==
  
To use OX Mail v2 you need to be running OX App Suite v7.8.4 or above together with the new Mobile API Facade. The Facade module provides an API optimized for mobile use-cases.
+
To use OX Mail you need to be running OX App Suite v7.8.4 or above together with the new Mobile API Facade. The Facade module provides an API optimized for mobile use-cases.
  
=== OX App Suite v7.8.4 ===
+
See [http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Mail_App OX System Requirements] for details.
 +
 
 +
=== OX App Suite ===
  
 
OX App Suite is a modular platform designed for Telcos, Hosters, and other Service Providers and delivers a wide range of cloud-based services. These include email, file sharing, collaborative document editing, document management, time management, cloud storage and metrics for monitoring end-user behavior. More information can be found at https://www.open-xchange.com/portfolio/whats-new/
 
OX App Suite is a modular platform designed for Telcos, Hosters, and other Service Providers and delivers a wide range of cloud-based services. These include email, file sharing, collaborative document editing, document management, time management, cloud storage and metrics for monitoring end-user behavior. More information can be found at https://www.open-xchange.com/portfolio/whats-new/
 
The OX Mail v2 app requires at least OX App Suite version 7.8.4-rev22.
 
  
 
=== Mobile API Facade ===
 
=== Mobile API Facade ===
Line 33: Line 33:
 
=== TLS 1.2 ===
 
=== TLS 1.2 ===
  
The communication between the OX Mail v2 app and its end points needs to be secured with TLS 1.2. Please make sure that your infrastructure is capable of handling TLS 1.2 HTTP requests without downgrading the connection.
+
The communication between the OX Mail app and its end points needs to be secured with TLS 1.2. Please make sure that your infrastructure is capable of handling TLS 1.2 HTTP requests without downgrading the connection.
  
 
= Pricing, Availability and Branding =
 
= Pricing, Availability and Branding =
  
== OX Mail v2 Availability ==
+
== OX Mail Availability ==
  
 
Users will be able to download their respective client for their device from the corresponding app store free of charge. The availability of the various clients depends on the approval process of the store provider. Clients for iOS and Android will be made available from the App Store and Google Play. The availability of the various clients will be confirmed by Open-Xchange via the usual communication channels.  
 
Users will be able to download their respective client for their device from the corresponding app store free of charge. The availability of the various clients depends on the approval process of the store provider. Clients for iOS and Android will be made available from the App Store and Google Play. The availability of the various clients will be confirmed by Open-Xchange via the usual communication channels.  
  
Please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales, for more information and pricing details about OX Mail v2.
+
Please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales, for more information and pricing details about OX Mail.
 +
 
 +
== Branding for Partners and Customers ==
 +
 
 +
With OX Mail it is possible for customers and partners to request the addition, and change, of a variety of branding elements in the app. This includes changing colors, graphical assets and icons.
 +
 
 +
For more information about branding, the cost of this service and what can be done please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales.
  
== OX Mail v1 Availability ==
+
== Auto Discovery Service ==
  
In accordance with the supported platform policy, Open-Xchange will discontinue maintenance and support for OX Mail v1.0 by end of Q1 2018. Existing customers with OX Mail v1.0 in their portfolio, please contact Open-Xchange Sales or send a mail to oxmailapp@open-xchange.com for further information.
+
The OX Mail app uses a central Auto Discovery Service to help new users to onboard to the app more easily.
  
There is no direct upgrade path for end users from the previous version of OX Mail to the latest. The OX Mail v1 is an online client and does not store anything locally. Therefore all email data is stored in App Suite and is immediately available in the OX Mail v2.
+
=== Prerequisits ===
  
One exception is the custom signature. It is stored in the App Suite but is not used by the OX Mail v2. The custom signature is therefore not lost, but also not accessible anymore.
+
Every provider that fulfills the following requirements may be added to the service to give their end users a better onboarding experience.
  
== Branding for Partners and Customers ==
+
* The OX App Suite v7.8.4 or higher
 +
* The OX Mobile Facade v1.0.9 or higher.
 +
* A working push configuration.
 +
* One or more MX records on the domains of all supported email addresses.
 +
 
 +
=== Required Information ===
 +
 
 +
The provider has to submit the following information:
  
With OX Mail v2 it is possible for customers and partners to request the addition, and change, of a variety of branding elements in the app. This includes changing colors, graphical assets and icons.
+
* The MX-record that the used email domains will use.
 +
* The URL to the OX App Suite. The URL has to be publicly reachable.
 +
* A test account to successfully log into the app.
 +
* An associated test email address. The domain of the test email address should use the same domain mapping to the MX records as the regular email addresses.
  
For more information about branding, the cost of this service and what can be done please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales.
+
Please send the required information to your Open-Xchange sales representative or oxmailapp@open-xchange.com.
  
 
= Download & Installation =
 
= Download & Installation =
Line 61: Line 77:
 
== Installation of the Clients ==
 
== Installation of the Clients ==
  
The OX Mail v2 is available via the different App Stores for iOS and Android:
+
The OX Mail is available via the different App Stores for iOS and Android:
  
* OX Mail v2 in Apple App Store
+
* [https://itunes.apple.com/us/app/ox-mail-v2/id1385582725 OX Mail in Apple App Store]
* OX Mail v2 in GooglePlay
+
* [https://play.google.com/store/apps/details?id=com.openxchange.mobile.oxmail OX Mail in GooglePlay]
 +
 
 +
OX Mail App is also available inside the OX App Suite user interface via the Client onboarding wizard. Further information can be found at: http://oxpedia.org/wiki/index.php?title=AppSuite:Client_Onboarding
  
 
== Installation of Mobile API Facade ==
 
== Installation of Mobile API Facade ==
Line 72: Line 90:
 
== Download & Installation of Packages ==
 
== Download & Installation of Packages ==
  
OX Mail v2 is available with the following backend packages:
+
OX Mail is available with the following backend packages:
  
 
* open-xchange-mobile-api-facade-push-certificates
 
* open-xchange-mobile-api-facade-push-certificates
 +
 +
To find the correct version of the package to be installed, please refer to http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade#Version_Matrix
  
 
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.
 
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.
Line 81: Line 101:
  
 
Add the following repositories to your Open-Xchange yum configuration:
 
Add the following repositories to your Open-Xchange yum configuration:
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
+
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
 
   
 
   
 
and run
 
and run
Line 90: Line 110:
  
 
Add the following repositories to your Open-Xchange yum configuration:
 
Add the following repositories to your Open-Xchange yum configuration:
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
+
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
 
   
 
   
 
and run
 
and run
Line 99: Line 119:
  
 
Add the following repositories to your Open-Xchange apt configuration:
 
Add the following repositories to your Open-Xchange apt configuration:
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
+
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
  
 
and run
 
and run
Line 106: Line 126:
 
  $ apt-get install open-xchange-mobile-api-facade-push-certificates
 
  $ apt-get install open-xchange-mobile-api-facade-push-certificates
  
=== SUSE Linux Enterprise Server 12 ===
+
=== Debian GNU/Linux 9.0 (Stretch; valid from v7.10) ===
 +
 
 
Add the following repositories to your Open-Xchange apt configuration:
 
Add the following repositories to your Open-Xchange apt configuration:
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
+
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
  
 
and run
 
and run
 +
 +
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade-push-certificates
  
$ zypper ref
+
=== Debian GNU/Linux 10.0 (Buster; valid from v7.10.3) ===
$ zypper install open-xchange-mobile-api-facade-push-certificates
 
 
 
= Setup and Configuration =
 
  
== Setup Middleware Notifications ==
+
Add the following repositories to your Open-Xchange apt configuration:
 +
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
  
The existing push framework of the Open-Xchange Middleware has been extended by the capability to spawn "permanent" listeners for incoming new message deliveries. Up to that point the life cycle for a listener was bound to at least one active session, which is associated with a client that is allowed to receive push notifications.
+
and run
 +
 +
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade-push-certificates
  
With introduction of the previously mentioned capability, listeners can be started without the need for an existent session right on the start of an Open-Xchange Middleware node. In addition those permanent listeners are spread approximately even over capable cluster members as - dependent on the underlying implementation - a listener representation may open/hold resources (socket connections) in order to receive notifications about new message deliveries.
+
=== SUSE Linux Enterprise Server 12 ===
 +
Add the following repositories to your Open-Xchange apt configuration:
 +
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=CUSTOMERID:PASSWORD|mobile-api-facade-restricted}}
  
To prepare a certain Open-Xchange Middleware node to spawn permanent push listeners the following properties need to be configured in file '/opt/open-xchange/etc/mail-push.properties':
+
and run
  
* com.openexchange.push.allowPermanentPush<br>This is the general switch to enable/disable support for permanent listeners on a node. Thus needs to be set to "true"
+
$ zypper ref
* com.openexchange.push.allowedClient<br>Specify the comma-separated list of clients which are allowed to receive notifications about new mails, “open-xchange-mobile-api-facade*” must be added here
+
$ zypper install open-xchange-mobile-api-facade-push-certificates
* com.openexchange.push.credstorage.enabled<br>As permanent listeners are required to run without an active session, the credential storage can be used to store user credentials in installations that do not support a master authentication to the mail storage. Hence, if the property com.openexchange.mail.passwordSource" (mail.properties) is not set to "global" this property is required to be set to "true"
 
* com.openexchange.push.credstorage.passcrypt<br>This property is required if "com.openexchange.push.credstorage.enabled" is set to "true". It does specify the passphrase to use to symmetrically encrypt the stored credentials. The passphrase is required to be equal on each cluster member.
 
* com.openexchange.push.credstorage.rdb<br>Once the credential storage is enabled, Open-Xchange offers two ways of storing the user-associated login/password combination. In cluster memory (default) or persisted to database. While the first way ensures that no user credentials are persisted anywhere in the Open-Xchange installation, it has the big disadvantage that stored credentials are gone once the last cluster member gets shut-down. Therefore there is also the possibility to store the credentials inside the database. Of course, no matter where the credentials are stored, they are encrypted using the value from com.openexchange.push.credstorage.passcrypt" property
 
  
With setting the properties above the configuration on the Open-Xchange Middleware node is prepared to spawn permanent listeners.
+
=== Univention Corporate Server ===
  
Now an appropriate push bundle/package needs to be installed that supports spawning permanent listeners. Currently Open-Xchange ships with three implementations:
+
If you have purchased the OX App Suite for UCS, the OX Mail App support is part of the offering. For installation of the OX Mail App push functionality please refer to the following steps:
  
* open-xchange-push-dovecot (also requires the optional open-xchange-rest package)
+
* Please make sure that the OX Customer Id has been entered in the UMC module "OX License Management" (Category "System").
* open-xchange-push-imapidle (Not recommended, therefore disabled for permanent listeners by default. com.openexchange.push.imapidle.supportsPermanentListeners=false)
+
* Open the UMC module "Repository Settings" (Category "Software"), activate the checkbox "mobileapirestricted200" resp. (depends on the installed OX version) and click on "Install".
* open-xchange-push-mailnotify
+
* The module shows a confirmation dialog that shows which packages will be installed if the installation of the push packages for OX Mail App is continued.
 +
* After installation open the UMC module "Domain Join" (Category "Domain") and execute all pending join scripts to complete installation.
  
Putting all together the following execution flow is taken to decide whether permanent listeners are spawned or not:
+
[[Image:Screenshot_mobileapriestricted_UCS.png|800px]]
  
[[Image:ox_mail_push_configuration_2.png|500px]]
+
= Setup and Configuration =
  
To check at any time what listeners are currently running, there is a new command-line tool "/opt/open-xchange/sbin/listpushusers" that outputs the user-id/context-id pair along-side with the information if the listener is of permanent nature or bound to an active session:
+
== Setup Middleware Notifications ==
 
 
[[Image:ox_mail_push_configuration_3.png|500px]]
 
  
An exemplary out put might look like:
+
'''Please find the up-to-date version of this section [https://documentation.open-xchange.com/latest/middleware/components/mailpush/mailpush.html#enable-permanent-mail-push-listeners here]'''
~# /opt/open-xchange/sbin/listpushusers
 
user=249, context=1, permanent=true
 
user=402, context=1, permanent=true
 
  
 
== Push Setup ==
 
== Push Setup ==
Line 160: Line 180:
 
== Setup Dovecot Push ==
 
== Setup Dovecot Push ==
  
=== Configuration of IMAP METADATA ===
+
'''Please find the up-to-date version of that section [https://documentation.open-xchange.com/latest/middleware/mail/dovecot/dovecot_push.html here]'''
 
 
Dovecot Push plug-in requires METADATA support on Dovecot side, but it should only be enabled for OX IMAP sessions and not for any other IMAP clients directly. Enabling can be done with e.g. the remote directive "remote 1.2.3.0/24 { imap_metadata = yes }" and specifying the IP ranges of OX.
 
 
 
Dovecot supports the [[https://tools.ietf.org/html/rfc5464|IMAP METADATA extension (RFC 5464)]], which allows per-mailbox, per-user data to be stored and accessed via IMAP commands.
 
 
 
To activate metadata storage, a [[Dictionary|dictionary]] needs to be configured in the Dovecot configuration using the {{{mail_attribute_dict}}} option.
 
 
 
To activate the IMAP METADATA commands, the imap_metadata and mail_attribute_dict options need to be activated.
 
 
 
Example:
 
 
 
# Store METADATA information within user's Maildir directory
 
mail_attribute_dict = file:%h/Maildir/dovecot-attributes
 
 
protocol imap {
 
imap_metadata = yes
 
}
 
 
 
The following picture should demonstrate how the overall communication flow between OX Mail v2, Open-Xchange Middleware, and the Dovecot Push plug-in takes place. That communication flow requires the "open-xchange-push-dovecot" and "open-xchange-rest" packages to be installed on the Open-Xchange Middleware nodes and the Dovecot "http-notify" plug-in.
 
 
 
[[Image:ox_mail_push_configuration_4.png|500px]]
 
 
 
Once the Open-Xchange Mail v2 is installed on the user’s mobile device and it is allowed to show notifications about a new message delivery, the OX Mail v2 performs a subscription call to the Open-Xchange Middleware Servers using a fully authenticated session.
 
 
 
When the "open-xchange-push-dovecot" package is installed, the previous subscribe call requests it to spawn a permanent listener. Such a listener simply tells the Dovecot server to notify about new message delivery events for the associated user by executing a special SETMETADATA command. Hence, it does not open or use any resources other than firing a single IMAP command to the Dovecot IMAP Server.
 
 
 
Whenever a "new message delivery" event occurs, the Dovecot Server performs a HTTP callback against a configurable HTTP end-point of the Open-Xchange Middleware providing crucial information about the newly delivered message with a simple JSON body. That incoming HTTP callback is then turned into an appropriate OSGi event with topic "com/openexchange/push".
 
 
 
That event is in turn handled by the Mobile Push event handler, which uses the event’s information to request an APN/GCM push to the mobile device.
 
 
 
=== Configuration of Dovecot "http-notify" plug-in ===
 
 
 
To use push notifications, both the "notify" and the "push_notification" plugins need to be activated. For LMTP delivery, this is required:
 
 
 
protocol lmtp {
 
mail_plugins = $mail_plugins notify push_notification
 
}
 
 
 
If you also want push notifications to work for LDA-based delivery, you would need additional configuration:
 
 
 
protocol lda {
 
mail_plugins = $mail_plugins notify push_notification
 
}
 
 
 
The HTTP end-point (URL + authentication information) to use is configured in the Dovecot configuration file. The appropriate configuration options will contain the HTTP URL denoting the end-point to connect to as well as the authentication information for Basic Authentication as configured by properties "com.openexchange.rest.services.basic-auth.login" and "com.openexchange.rest.services.basic-auth.password".
 
The URL to configure in Dovecot configuration follows this pattern.
 
 
 
<http|https> + "://" + <login> + ":" + <password> + "@" + <host> + ":" + <port> + "/preliminary/http-notify/v1/notify"
 
 
 
E.g.
 
 
 
plugin {
 
push_notification_driver = ox:url=http://login:pass@node1.domain.tld:8009/preliminary/http-notify/v1/notify
 
}
 
 
 
Furthermore, it is also possible to specify more than one HTTP end-point to connect to if a new message delivery occurs. Thus the configuration section mentioned above may be extended by additional "push_notification_driver" entries; e.g. push_notification_driver2, push_notification_driver3, etc.
 
 
 
Please note that the path "/preliminary/http-notify/v1/notify" denotes the internal REST API of the Open-Xchange Middleware, which is not publicly accessible. The administrator can decide whether to add that path to the Apache configuration (see also [[AppSuite:Apache_Configuration]] and [[AppSuite:Grizzly]]) through a
 
Location/ProxyPass directive:
 
 
 
<Location /preliminary>
 
Order Deny,Allow
 
Deny from all
 
# Only allow access from servers within the network. Do not expose this
 
# location outside of your network. In case you use a load balancing service in front
 
# of your Apache infrastructure you should make sure that access to /preliminary will
 
# be blocked from the internet / outside clients. Examples:
 
# Allow from 192.168.0.1
 
# Allow from 192.168.1.1 192.168.1.2
 
# Allow from 192.168.0.
 
ProxyPass /preliminary balancer://oxcluster/preliminary
 
</Location>
 
 
 
In case the "user=" sent by OX in the push_notification_driver url data does not match the IMAP login of a user, Dovecot ignores it. This can be overridden by defining "user_from_metadata" in the push_notification_driver url, e.g.
 
 
 
push_notification_driver = ox:url=http://example.com/ user_from_metadata
 
  
 
== Setup App Notifications ==
 
== Setup App Notifications ==
  
There are two possible ways to setup notifications for new mails from the Middleware to the new OX Mail v2 apps. One is to install the push configuration provideded in the open-change-mobile-api-facade-push-certificates pacakge, the other is to configure everything manually.
+
'''Please find the up-to-date version of this section [https://documentation.open-xchange.com/latest/middleware/mail/mail_push.html#setup-new-mail-notifications-to-ox-mail-v2-0 here]'''
 
 
=== Push configuration provided by package ===
 
 
 
To be able to use the push configuration provideded in the open-change-mobile-api-facade-push-certificates pacakge its needed to enabled push notifications for Android and iOS in general first. This can be done in a file 'pns.properties' (which might need to be created first):
 
 
 
* com.openexchange.pns.transport.apn.ios.enabled=true<br>General switch to enable/disable push notifications for iOS using the Apple APN service
 
* com.openexchange.pns.transport.gcm.enabled=true<br>General switch to enable/disable push notifications for iOS using the Google FCM service
 
 
 
=== Manually configuring push configurations ===
 
 
 
To manually configure push configurations for Android you need to configure a service key in the Google Firebase developer console, for iOS you need to request a certificate for push notifications in the Apple developer console.
 
 
 
Generally push notifications for both platforms needs to be enabled in the file 'pns.properties':
 
 
 
* com.openexchange.pns.transport.apn.ios.enabled=true<br>General switch to enable/disable push notifications for iOS using the Apple APN service
 
* com.openexchange.pns.transport.gcm.enabled=true<br>General switch to enable/disable push notifications for iOS using the Google FCM service
 
 
 
For Android the file 'pns-gcm-options.yml' needs to contain the following snippet with the proper server key:
 
open-xchange-mobile-api-facade:
 
    enabled: true
 
    key: 1234567890123456789012345678901234567890
 
 
 
For Apple iOS the file 'pns-apns-options.yml' needs to contain the following snippet with the proper values:
 
open-xchange-mobile-api-facade:
 
    enabled: true
 
    keystore: /opt/open-xchange/etc/apns-certificate.p12
 
    password: 12345678
 
    production: true
 
 
 
The identifier 'open-xchange-mobile-api-facade' might be different. When we provide multiple branded apps connecting to the same servers we append a specific string per brand, e.g. 'open-xchange-mobile-api-facade-brand1' and 'open-xchange-mobile-api-facade-brand2'.
 
  
 
= Known Limitations =
 
= Known Limitations =
Line 276: Line 190:
 
== Flagging ==
 
== Flagging ==
  
Starting with version v7.8.4 the OX App Suite supports flagging modes described here: https://documentation.open-xchange.com/7.8.4/middleware/components/mail_flagging.html. There are four different modes defined. These modes describe the handling of the IMAP FLAGGED flag and color flagging and how both work together. The OX Mail v2 support only two modes, "Flagged only" and "Flagged implicit". All users using the OX Mail v2 should be provisioned with one of these modes. The other two modes, "Color only" and "Flagged and color" are not supported currently and might cause bad user experience when the app is used in conjunction with other mail user agents.
+
Starting with version v7.8.4 the OX App Suite supports flagging modes described here: https://documentation.open-xchange.com/7.8.4/middleware/components/mail_flagging.html. There are four different modes defined. These modes describe the handling of the IMAP FLAGGED flag and color flagging and how both work together. The OX Mail support only two modes, "Flagged only" and "Flagged implicit". All users using the OX Mail should be provisioned with one of these modes. The other two modes, "Color only" and "Flagged and color" are not supported currently and might cause bad user experience when the app is used in conjunction with other mail user agents.
  
 
== Settings ==
 
== Settings ==
  
The settings from the OX App Suite are not used by the OX Mail v2 app. This includes the signature so that it has to be maintained manually both in the OX App Suite and the OX Mail v2 app. Settings are also only available locally and not synced when using the app on multiple devices.
+
The settings from the OX App Suite are not used by the OX Mail app. This includes the signature so that it has to be maintained manually both in the OX App Suite and the OX Mail app. Settings are also only available locally and not synced when using the app on multiple devices.
 
 
== Multiple Account Support ==
 
 
 
This version of the OX Mail v2 app does not support the use of multiple accounts. The consequence is that only the primary OX App Suite account is usable from the app.
 
  
 
== Threading ==
 
== Threading ==

Latest revision as of 15:15, 17 January 2020

OX Mail

The OX Mail is a companion app for OX App Suite, and brings the power of OX App Suite web-based email to your customers' mobile devices. The OX Mail is a native app designed specifically for Android and iOS smartphones and tablets.

With a focus on security and user-experience, OX Mail serves all your email needs on the go. Most notably you can answer and process mails even when you are offline, mails are synced when you go online. For completing addresses, OX Mail uses the address book of the device along with all received and sent mails. When you have deleted an email by accident, you can easily undo that. Furthermore OX Mail provides a list of known features such as pushing new emails onto your device, supporting mail folders, handling attachments, showing the number of unread email, and so on.

Key Benefits

  • Additional privacy and integration with OX Abuse Shield
  • Offline availability
  • Branding for customized design
  • Grouping notifications on Android
  • Mobile API facade to connect to OX App Suite

Open-Xchange now provides more detailed overviews and Feature Overview documents relating to new product releases. These can be found at https://www.open-xchange.com/portfolio/whats-new/

This app is brought to you by Open-Xchange. You can choose between using our OX-branded app as part of your OX App Suite license or to order a version that is adapted to your brand and published under your name.

Requirements

To use OX Mail you need to be running OX App Suite v7.8.4 or above together with the new Mobile API Facade. The Facade module provides an API optimized for mobile use-cases.

See OX System Requirements for details.

OX App Suite

OX App Suite is a modular platform designed for Telcos, Hosters, and other Service Providers and delivers a wide range of cloud-based services. These include email, file sharing, collaborative document editing, document management, time management, cloud storage and metrics for monitoring end-user behavior. More information can be found at https://www.open-xchange.com/portfolio/whats-new/

Mobile API Facade

The Mobile API Facade is a server component that brings the new native mobile mail apps together with the OX App Suite. We’ve built the facade based on the technology used and proven in the OX App Suite middleware. The facade is developed in Java, utilizing the OSGIFramework. Further information can be found at: http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade.

TLS 1.2

The communication between the OX Mail app and its end points needs to be secured with TLS 1.2. Please make sure that your infrastructure is capable of handling TLS 1.2 HTTP requests without downgrading the connection.

Pricing, Availability and Branding

OX Mail Availability

Users will be able to download their respective client for their device from the corresponding app store free of charge. The availability of the various clients depends on the approval process of the store provider. Clients for iOS and Android will be made available from the App Store and Google Play. The availability of the various clients will be confirmed by Open-Xchange via the usual communication channels.

Please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales, for more information and pricing details about OX Mail.

Branding for Partners and Customers

With OX Mail it is possible for customers and partners to request the addition, and change, of a variety of branding elements in the app. This includes changing colors, graphical assets and icons.

For more information about branding, the cost of this service and what can be done please message oxmailapp@open-xchange.com, or contact Open-Xchange Sales.

Auto Discovery Service

The OX Mail app uses a central Auto Discovery Service to help new users to onboard to the app more easily.

Prerequisits

Every provider that fulfills the following requirements may be added to the service to give their end users a better onboarding experience.

  • The OX App Suite v7.8.4 or higher
  • The OX Mobile Facade v1.0.9 or higher.
  • A working push configuration.
  • One or more MX records on the domains of all supported email addresses.

Required Information

The provider has to submit the following information:

  • The MX-record that the used email domains will use.
  • The URL to the OX App Suite. The URL has to be publicly reachable.
  • A test account to successfully log into the app.
  • An associated test email address. The domain of the test email address should use the same domain mapping to the MX records as the regular email addresses.

Please send the required information to your Open-Xchange sales representative or oxmailapp@open-xchange.com.

Download & Installation

Installation of the Clients

The OX Mail is available via the different App Stores for iOS and Android:

OX Mail App is also available inside the OX App Suite user interface via the Client onboarding wizard. Further information can be found at: http://oxpedia.org/wiki/index.php?title=AppSuite:Client_Onboarding

Installation of Mobile API Facade

Installation Guide and configuration options can be found under: http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade

Download & Installation of Packages

OX Mail is available with the following backend packages:

  • open-xchange-mobile-api-facade-push-certificates

To find the correct version of the package to be installed, please refer to http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade#Version_Matrix

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

Redhat Enterprise Linux 6 or CentOS 6

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade-restricted]
name=Open-Xchange-mobile-api-facade-restricted
baseurl=https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum install open-xchange-mobile-api-facade-push-certificates

Redhat Enterprise Linux 7 or CentOS 7

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade-restricted]
name=Open-Xchange-mobile-api-facade-restricted
baseurl=https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum install open-xchange-mobile-api-facade-push-certificates

Debian GNU/Linux 8.0 (Jessie)

Add the following repositories to your Open-Xchange apt configuration:

deb https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/DebianJessie /

and run

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade-push-certificates

Debian GNU/Linux 9.0 (Stretch; valid from v7.10)

Add the following repositories to your Open-Xchange apt configuration:

deb https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/DebianStretch /

and run

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade-push-certificates

Debian GNU/Linux 10.0 (Buster; valid from v7.10.3)

Add the following repositories to your Open-Xchange apt configuration:

deb https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/DebianBuster /

and run

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade-push-certificates

SUSE Linux Enterprise Server 12

Add the following repositories to your Open-Xchange apt configuration:

$ zypper ar https://CUSTOMERID:PASSWORD@software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade-restricted/SLE_12 mobile-api-facade-restricted

and run

$ zypper ref
$ zypper install open-xchange-mobile-api-facade-push-certificates

Univention Corporate Server

If you have purchased the OX App Suite for UCS, the OX Mail App support is part of the offering. For installation of the OX Mail App push functionality please refer to the following steps:

  • Please make sure that the OX Customer Id has been entered in the UMC module "OX License Management" (Category "System").
  • Open the UMC module "Repository Settings" (Category "Software"), activate the checkbox "mobileapirestricted200" resp. (depends on the installed OX version) and click on "Install".
  • The module shows a confirmation dialog that shows which packages will be installed if the installation of the push packages for OX Mail App is continued.
  • After installation open the UMC module "Domain Join" (Category "Domain") and execute all pending join scripts to complete installation.

Screenshot mobileapriestricted UCS.png

Setup and Configuration

Setup Middleware Notifications

Please find the up-to-date version of this section here

Push Setup

The push setup requires a working OX App Suite and the Mobile API Facade.

Simply said the main purpose of the Mobile Push functionality is to register an OSGi event handler converting an incoming OSGi event with topic "com/openexchange/push" to an appropriate native push reaching the mobile device using either APN or GCM.

Setup Dovecot Push

Please find the up-to-date version of that section here

Setup App Notifications

Please find the up-to-date version of this section here

Known Limitations

Flagging

Starting with version v7.8.4 the OX App Suite supports flagging modes described here: https://documentation.open-xchange.com/7.8.4/middleware/components/mail_flagging.html. There are four different modes defined. These modes describe the handling of the IMAP FLAGGED flag and color flagging and how both work together. The OX Mail support only two modes, "Flagged only" and "Flagged implicit". All users using the OX Mail should be provisioned with one of these modes. The other two modes, "Color only" and "Flagged and color" are not supported currently and might cause bad user experience when the app is used in conjunction with other mail user agents.

Settings

The settings from the OX App Suite are not used by the OX Mail app. This includes the signature so that it has to be maintained manually both in the OX App Suite and the OX Mail app. Settings are also only available locally and not synced when using the app on multiple devices.

Threading

The used backend should support RFC 5256 in order for the app to show threads correctly. Dovecot is supporting this RFC out of the box. If the backend doesn't support RCF 5256 its possible to disable to disable threading support in the Mobile API Facade by configuring the following property in facade.properties:

com.openexchange.mobile.api.facade.threading=disabled