protonmail-api

Unofficial API for interacting with ProtonMail.

Allows interaction with ProtonMail through a simple Node.js API. Leverages the official WebClient, keeping with the spirit of security and privacy. Currently supports sending email, managing email/conversations, and managing labels and folders. See the documentation for full functionality.

This project is not endorsed or supported by Proton Technologies AG.

Quick Start

Setup

npm install protonmail-api

Send an Email

const ProtonMail = require('protonmail-api');

(async () => {
  const pm = await ProtonMail.connect({
    username: '[e-mail]',
    password: 'somethingsecure'
  })

  await pm.sendEmail({
    to: '[e-mail]',
    subject: 'Send email tutorial',
    body: 'Hello world'
  })

  pm.close()
})()

More Examples

Numerous examples can be found in the tutorials section of the documentation.

Documentation

Full documentation found here

How?

This library uses Puppeteer (headless Chromium) to load and control the official ProtonMail WebClient.

The first attempt at building this was by trying to reverse engineer the API from the WebClient. This proved to be difficult and fragile. By utilizing the AngularJS modules (through the headless browser) this library is able to leverage all the work that goes into the official WebClient. This also means complex and sensitive things (like cryptography) are not handled by this library. The main drawback to this approach is the added weight of Puppeteer.

Contributing

This project is looking for maintainers and contributors. Please contact [e-mail] if you are interested.

To run integration tests you need to provide a ProtonMail account. It is best to use a dedicated testing account without any filters. The credentials are set as environment variables PM_USERNAME and PM_PASSWORD.

Example:

PM_USERNAME=[e-mail] PM_PASSWORD=kgjSOE223qWer npm run test

Or create a .env file (in this directory next to package.json:

PM_USERNAME=[e-mail]
PM_PASSWORD=kgjSOE223qWer