mirror of
https://github.com/the-djmaze/snappymail.git
synced 2026-09-03 22:47:03 +03:00
140 lines
4.6 KiB
Markdown
140 lines
4.6 KiB
Markdown
# postal-mime
|
|
|
|
Email parser for browser environments.
|
|
|
|
PostalMime can be run in the main web thread or from Web Workers.
|
|
|
|
PostalMime can be bundled using WebPack. In fact the distribution file is also built with WebPack.
|
|
|
|
## Source
|
|
|
|
Source code is available from [Github](https://github.com/postalsys/postal-mime).
|
|
|
|
## Demo
|
|
|
|
See this [example](https://kreata.ee/postal-mime/example/).
|
|
|
|
## Usage
|
|
|
|
### Free, AGPL-licensed version
|
|
|
|
First install the module from npm:
|
|
|
|
```
|
|
$ npm install postal-mime
|
|
```
|
|
|
|
next import the PostalMime class into your script:
|
|
|
|
```js
|
|
const { PostalMime } = require('postal-mime');
|
|
```
|
|
|
|
or when using as a global
|
|
|
|
```html
|
|
<script src="/path/to/postal-mime.js"></script>
|
|
<script>
|
|
const PostalMime = postalMime.default;
|
|
</script>
|
|
```
|
|
|
|
### MIT version
|
|
|
|
MIT-licensed version is available for [Postal Systems subscribers](https://postalsys.com/).
|
|
|
|
First install the module from Postal Systems private registry:
|
|
|
|
```
|
|
$ npm install @postalsys/postal-mime
|
|
```
|
|
|
|
next import the postal-mime class into your script:
|
|
|
|
```js
|
|
const { PostalMime } = require('@postalsys/postal-mime');
|
|
```
|
|
|
|
If you have already built your application using the free version of postal-mime and do not want to modify require statements in your code, you can install the MIT-licensed version as an alias for "postal-mime".
|
|
|
|
```
|
|
$ npm install postal-mime@npm:@postalsys/postal-mime
|
|
```
|
|
|
|
This way you can keep using the old module name
|
|
|
|
```js
|
|
const { PostalMime } = require('postal-mime');
|
|
```
|
|
|
|
### Promises
|
|
|
|
All postal-mime methods use Promises, so you need to wait using `await` or wait for the `then()` method to fire until you get the response.
|
|
|
|
```js
|
|
const { PostalMime } = require('postal-mime');
|
|
const parser = new PostalMime();
|
|
const email = await parser.parse(email);
|
|
console.log(email.subject);
|
|
console.log(email.html);
|
|
```
|
|
|
|
### Node.js
|
|
|
|
Even though PostalMime is built for the browser environment you can also use it in Node.js with a few tweaks. Notably you'd need to register a global _Blob_ class that is not available by default in Node.
|
|
|
|
```js
|
|
// Set up global Blob
|
|
// $ npm install cross-blob
|
|
globalThis.Blob = require('cross-blob');
|
|
// Require Node.js version of the library
|
|
const PostalMime = require('postal-mime/dist/node').postalMime.default;
|
|
|
|
// Use PostalMime as you'd normally do
|
|
new PostalMime().parse('Subject: test').then(res => console.log(res));
|
|
```
|
|
|
|
#### parser.parse()
|
|
|
|
```js
|
|
parser.parse(email) -> Promise
|
|
```
|
|
|
|
Where
|
|
|
|
- **email** is the rfc822 formatted email. Either a string, an ArrayBuffer, a Blob object or a Node.js Buffer
|
|
|
|
> **NB** you can call `parse()` only once. If you need to parse another message, create a new _PostalMime_ object.
|
|
|
|
This method parses an email message into a structured object with the following properties:
|
|
|
|
- **headers** is an array of headers in the same order as found from the message (topmost headers first).
|
|
- **headers[].key** is lowercase key of the header line, eg. `"dkim-signature"`
|
|
- **headers[].value** is the unprocessed value of the header line
|
|
- **from**, **sender**, **replyTo** includes a processed object for the corresponding headers
|
|
- **from.name** is decoded name (empty string if not set)
|
|
- **from.address** is the email address
|
|
- **deliveredTo**, **returnPath** is the email address from the corresponding header
|
|
- **to**, **cc**, **bcc** includes an array of processed objects for the corresponding headers
|
|
- **to[].name** is decoded name (empty string if not set)
|
|
- **to[].address** is the email address
|
|
- **subject** is the email subject line
|
|
- **messageId**, **inReplyTo**, **references** includes the value as found from the corresponding header without any processing
|
|
- **date** is the email sending time formatted as an ISO date string (unless parsing failed and in this case the original value is used)
|
|
- **html** is the HTML content of the message as a string
|
|
- **text** is the plaintext content of the message as a string
|
|
- **attachments** is an array that includes message attachments
|
|
- **attachment[].filename** is the file name if provided
|
|
- **attachment[].mimeType** is the MIME type of the attachment
|
|
- **attachment[].disposition** is either "attachment", "inline" or `null` if disposition was not provided
|
|
- **attachment[].related** is a boolean value that indicats if this attachment should be treated as embedded image
|
|
- **attachment[].contentId** is the ID from Content-ID header
|
|
- **attachment[].content** is an ArrayBuffer that contains the attachment file
|
|
|
|
## License
|
|
|
|
© 2021 Andris Reinman
|
|
|
|
Licensed under GNU Affero General Public License v3.0 or later.
|
|
|
|
MIT-licensed version of postal-mime is available for [Postal Systems subscribers](https://postalsys.com/).
|