Skip to content

Guidelines for email providers

Jump to bottom
Bernhard edited this page Aug 31, 2022 · 4 revisions

Test the integration and report issues

Designed as a universal toolbox for enhancing web applications with PGP encryption, Mailvelope works with a wide range of email providers and websites. Please follow https://mailvelope.com/en/faq/#not_on_list to activate Mailvelope for your web application and let us know if you run into any issues.

Inclusion in the default authorized domain list

Mailvelope is shipped with a set of default authorized domains, which are supported by Mailvelope out of the box. Even if not included in the default authorized domain list, you can instruct your users to activate Mailvelope for your domain with the FAQ link provided above.

As we’re often asked to include new websites to our default domain list, we decided to set up some criteria for this process.

First of all: We appreciate your interest in cooperating with Mailvelope and we would like to support you with the integration. Please ensure that you’ve taken the following steps, before applying for inclusion to our default domain list:

  • Your application is live and has a significant number of users (100k and above).
  • Mention on your website that your application can be used in combination with the Mailvelope extension and provide links to www.mailvelope.com.
  • Make sure Mailvelope works by thoroughly testing all possible scenarios (on Firefox, Chrome and Edge). Should you find a malfunction which is caused by Mailvelope, we’re glad to hear from you as we’re always striving to improve our product. In case of limitations due to your specific environment, please communicate them to your users.
  • Provide a documentation how to use Mailvelope with your application. The documentation should include at least the setup process.
  • Be prepared to provide at least minimal support for your users with Mailvelope. You can link to our FAQ and documentation, but please understand, that the support we can provide to your users is limited. Therefore we would expect that you can provide first level support and all questions which may arise are first directed to your own support team. If you should need further support to integrate Mailvelope into your product, don’t hesitate to contact us for an individual support offer.

Trigger inclusion in the authorized domain list from your application

Alternatively, if your web application is not part of the default authorized domain list, there is a way that you can help your users with the activation step. Mailvelope offers an interface that allows your application to request inclusion in the authorized domain list for each visitor of your website that has Mailvelope installed.

The request is triggered by loading an invisible iframe (<iframe style="display: none;" src="https://api.mailvelope.com/authorize-domain/?api=false" />) that will initiate the activation process in Mailvelope.

The procedure is also documented on our demo site: https://demo.mailvelope.com/manual

Seamless Integration via client API or Web Components

As you may have noticed, some email providers connect to Mailvelope directly via our client API. Instead of Mailvelope having to analyze the host page during runtime, the web application is instead utilizing UI components of Mailvelope to process PGP messages. The user experience with this approach is considerably better and we encourage you to use this possibility.

Generally there are two options here: A JavaScript client API and the somewhat newer light version with Web Components. Further documentation is available here:

Client-API

Web Components

Note: For the demo pages you have to import the following private key: https://demo.mailvelope.com/

JSDoc of the client API is available in this file: https://github.com/mailvelope/mailvelope/blob/master/src/client-API/client-api.js

Notes on multiple keyrings

The client API allows authorized web applications to create individual keyrings in Mailvelope. For example, on the demo page a custom keyring is created with createKeyring. We would rather consider this an outdated approach and recommend instead to use the getKeyring() call without parameters to directly access the main Mailvelope keyring. This is also the way the web components work.

Notes on key discovery

When calling editor.encrypt, non-existing keys are automatically imported into Mailvelope via the Mailvelope Key Server or WKD. If no public key can be determined, then an error occurs.

After the user has entered a recipient email address in the webmail UI, you might want to check if a public key is available for this user ID. Otherwise further actions are required by the user to import the required public key.

With keyring.validKeyForAddress you can check if a key is available. And use one of the following options to proceed:

1.

  • validate all recipients with keyring.validKeyForAddress
  • when calling editor.encrypt, Mailvelope automatically imports the keys which are available but not yet in the local keyring

2.

  • validate the recipient with keyring.validKeyForAddress, Mailvelope returns the armored block of the key (property: content) in the return value.
  • with keyring.importPublicKey() the web application triggers the import of the key
  • with editor.encrypt it is no longer necessary to import automatically because the keys have already been imported

Home

API support
Security

Clone this wiki locally