puppeteer-email
Version:
Email automation driven by headless chrome.
175 lines (125 loc) • 8.18 kB
Markdown
# puppeteer-email
> Email automation drive by headless chrome.
[](https://www.npmjs.com/package/puppeteer-email) [](https://travis-ci.com/transitive-bullshit/puppeteer-email) [](https://standardjs.com)
## Install
```bash
npm install --save puppeteer-email
```
## Usage
This example signs into an [Outlook](https://outlook.live.com) account, searches for a given query, and then parses and returns all emails returned for that query.
```js
const PuppeteerEmail = require('puppeteer-email')
const client = new PuppeteerEmail('outlook')
const username = 'xxx'
const password = 'xxx'
const session = await client.signin({ username, password })
const emails = await session.getEmails({ query: 'from:github' })
await session.close()
console.log(emails)
```
Example parsed email output:
```js
[
{
"attachments": [ /* ... */ ],
"headers": { /* ... */ },
"html": "<!DOCTYPE html>\n<html>...</html>",
"text": "...",
"textAsHtml": "<p>...</p>",
"subject": "Example email subject",
"date": "2018-05-09T14:17:02.000Z",
"to": {
"value": [
{
"address": "fischxxxx@outlook.com",
"name": "Travis Fischer"
}
],
"html": "<span class=\"mp_address_name\">Travis Fischer</span> <<a href=\"mailto:fischxxxx@outlook.com\" class=\"mp_address_email\">fischxxxx@outlook.com</a>>",
"text": "Travis Fischer <fischxxxx@outlook.com>"
},
"from": {
"value": [
{
"address": "noreply@github.com",
"name": "GitHub"
}
],
"html": "<span class=\"mp_address_name\">GitHub</span> <<a href=\"mailto:noreply@github.com\" class=\"mp_address_email\">noreply@github.com</a>>",
"text": "GitHub <noreply@github.com>"
},
"messageId": "<01.B3.11399.xxxxxxxx@momentum1-mta1>"
}
]
```
See [parse-email](https://github.com/transitive-bullshit/parse-email) for details on email model properties.
## API
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
- [PuppeteerEmail](#puppeteeremail)
- [provider](#provider)
- [signup](#signup)
- [signin](#signin)
### [PuppeteerEmail](https://github.com/transitive-bullshit/puppeteer-email/blob/f5e0b1eac196eb5665c862c6e2556b32c3ce6c0e/packages/puppeteer-email/index.js#L28-L131)
Main entrypoint for authenticating and automating a given email provider.
Type: `function (provider)`
- `provider` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | PuppeteerEmailProvider)** Name of built-in email provider or an
email address belonging to a built-in email provider. May also be an instance of a
custom PuppeteerEmailProvider.
Examples:
```javascript
const client = new PuppeteerEmail('outlook')
const session = await client.signin({ username: 'xxx', password: 'xxx' })
const emails = await session.getEmails({ query: 'from:amazon' })
await session.close()
```
```javascript
const client = new PuppeteerEmail('test@outlook.com')
const session = await client.signin({ email: 'test@outlook.com', password: 'xxx' })
await session.close()
```
* * *
#### [provider](https://github.com/transitive-bullshit/puppeteer-email/blob/f5e0b1eac196eb5665c862c6e2556b32c3ce6c0e/packages/puppeteer-email/index.js#L45-L45)
Email provider to automate.
Type: PuppeteerEmailProvider
* * *
#### [signup](https://github.com/transitive-bullshit/puppeteer-email/blob/f5e0b1eac196eb5665c862c6e2556b32c3ce6c0e/packages/puppeteer-email/index.js#L71-L88)
Creates a new email account using the set email provider.
Any user information that isn't provided will be filled in using
[faker.js](https://github.com/Marak/Faker.js).
Returns an email session with the authenticated puppeteer browser.
Type: `function (user, opts)`
- `user` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** User info for the account to create
- `user.username` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Username
- `user.password` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Password
- `user.firstName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** User's given name
- `user.lastName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** User's family name
- `user.birthday` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** User's birthday
- `user.birthday.month` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** User's birthday month
- `user.birthday.day` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** User's birthday day
- `user.birthday.year` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** User's birthday year
- `opts` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Options (optional, default `{}`)
- `opts.browser` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Puppeteer browser instance to use
- `opts.puppeteer` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Puppeteer [launch options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions)
* * *
#### [signin](https://github.com/transitive-bullshit/puppeteer-email/blob/f5e0b1eac196eb5665c862c6e2556b32c3ce6c0e/packages/puppeteer-email/index.js#L108-L130)
Signs into an existing email account using the set email provider.
You must specify either `user.username` or `user.email`.
Returns an email session with the authenticated puppeteer browser.
Type: `function (user, opts)`
- `user` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** User info for the account to sign into
- `user.username` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Username (implies email)
- `user.email` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Email (implies username)
- `user.password` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Password
- `opts` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Options (optional, default `{}`)
- `opts.browser` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Puppeteer browser instance to use
- `opts.puppeteer` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Puppeteer [launch options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions)
* * *
## Related
- [puppeteer-email-cli](../puppeteer-email-cli) - CLI for executing one-off email automation tasks.
- [puppeteer-email-session](../puppeteer-email-session) - Holds state for an authenticated puppeteer email session.
- [parse-email](https://github.com/transitive-bullshit/parse-email) - Parses mime-encoded email messages.
## Disclaimer
Using this software to violate the terms and conditions of any third-party service is strictly against the intent of this software. By using this software, you are acknowledging this fact and absolving the author or any potential liability or wrongdoing it may cause. This software is meant for testing and experimental purposes only, so please act responsibly.
## License
MIT © [Travis Fischer](https://github.com/transitive-bullshit)