forked from nodemailer/mailparser
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathdocumentation.html
172 lines (172 loc) · 13.9 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
<div id="body-inner">
<h1>Mailparser</h1>
<h1 id="nb-this-project-is-deprecated">NB! This project is deprecated</h1>
<p>All users of this project are urged to find an alternative as it is not maintained anymore. Read more <a href="https://blog.nodemailer.com/2018/03/11/spring-cleaning/" class="highlight">here</a></p>
<hr>
<p>Advanced email parser for Node.js. Everything is handled as a stream which should make it able to parse even very large messages (100MB+) with relatively low overhead.</p>
<p>The module exposes two separate modes, a lower level <strong>MailParser</strong> class and <strong>simpleParser</strong> function. The latter is simpler to use (hence the name) but is less resource efficient as it buffers attachment contents in memory.</p>
<h2 id="install">Install <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#install"><i class="fa fa-link fa-lg"></i></span></h2>
<pre><code class="language-bash hljs">npm install mailparser --save
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<h2 id="simpleparser">simpleParser <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#simpleparser"><i class="fa fa-link fa-lg"></i></span></h2>
<p><strong>simpleParser</strong> is the easiest way to parse emails. You only need to provide a message source to get a parsed email structure in return. As an additional bonus all embedded images in HTML (eg. the images that point to attachments using cid: URIs) are replaced with base64 encoded data URIs, so the message can be displayed without any additional processing. Be aware though that this module does not do any security cleansing (eg. removing javascript and so on), this is left to your own application.</p>
<pre><code class="language-javascript hljs"><span class="hljs-keyword">const</span> simpleParser = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mailparser'</span>).simpleParser;
simpleParser(source, (err, mail)=>{})
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<p>or as a Promise:</p>
<pre><code class="language-javascript hljs">simpleParser(source).then(mail=>{}).catch(err=>{})
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<p>Where</p>
<ul>
<li><strong>source</strong> is either a stream, a Buffer or a string that needs to be parsed</li>
<li><strong>err</strong> is the possible error object</li>
<li><strong>mail</strong> is a structured email object</li>
</ul>
<h3 id="mail-object">mail object <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#mail-object"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Parsed <strong>mail</strong>* object has the following properties</p>
<ul>
<li><strong>headers</strong> – a Map object with lowercase header keys</li>
<li><strong>subject</strong> is the subject line (also available from the header <em>mail.headers.get(‘subject’)</em>)</li>
<li><strong>from</strong> is an address object for the From: header</li>
<li><strong>to</strong> is an address object for the To: header</li>
<li><strong>cc</strong> is an address object for the Cc: header</li>
<li><strong>bcc</strong> is an address object for the Bcc: header (usually not present)</li>
<li><strong>date</strong> is a Date object for the Date: header</li>
<li><strong>messageId</strong> is the Message-ID value string</li>
<li><strong>inReplyTo</strong> is the In-Reply-To value string</li>
<li><strong>reply-to</strong> is an address object for the Cc: header</li>
<li><strong>references</strong> is an array of referenced Message-ID values</li>
<li><strong>html</strong> is the HTML body of the message. If the message included embedded images as cid: urls then these are all replaced with base64 formatted data: URIs</li>
<li><strong>text</strong> is the plaintext body of the message</li>
<li><strong>textAsHtml</strong> is the plaintext body of the message formatted as HTML</li>
<li><strong>attachments</strong> is an array of attachments</li>
</ul>
<h3 id="address-object">address object <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#address-object"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Address objects have the following structure:</p>
<ul>
<li><p><strong>value</strong> an array with address details</p>
<ul>
<li><strong>name</strong> is the name part of the email/group</li>
<li><strong>address</strong> is the email address</li>
<li><strong>group</strong> is an array of grouped addresses</li>
</ul></li>
<li><p><strong>text</strong> is a formatted address string for plaintext context</p></li>
<li><p><strong>html</strong> is a formatted address string for HTML context</p></li>
</ul>
<p><strong>Example</strong></p>
<pre><code class="language-javascript hljs">{
value: [
{
address: <span class="hljs-string">'[email protected]'</span>,
name: <span class="hljs-string">'Andris Reinman'</span>
},
{
address: <span class="hljs-string">'[email protected]'</span>,
name: <span class="hljs-string">''</span>
}
],
html: <span class="hljs-string">'<span class="mp_address_name">Andris Reinman</span> <<a href="mailto:[email protected]" class="mp_address_email">[email protected]</a>>, <a href="mailto:[email protected]" class="mp_address_email">[email protected]</a>'</span>,
text: <span class="hljs-string">'Andris Reinman <[email protected]>, [email protected]'</span>
}
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<h3 id="headers-map">headers Map <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#headers-map"><i class="fa fa-link fa-lg"></i></span></h3>
<p><strong>headers</strong> is a Map with lowercase header keys. So if you want to check for the Subject: header then you can do it like this:</p>
<pre><code class="language-javascript hljs"><span class="hljs-keyword">if</span> (mail.headers.has(<span class="hljs-string">'subject'</span>)) {
<span class="hljs-built_in">console</span>.log(mail.headers.get(<span class="hljs-string">'subject'</span>));
}
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<p>The format of a header depends on the specific key. For most header keys the value is either a string (a single header) or an array of strings (multiple headers with the same key were found).</p>
<p>Special header keys are the following:</p>
<ol>
<li><p>All address headers are converted into address objects</p>
<ul>
<li><strong>from</strong></li>
<li><strong>to</strong></li>
<li><strong>cc</strong></li>
<li><strong>bcc</strong></li>
<li><strong>sender</strong></li>
<li><strong>reply-to</strong></li>
<li><strong>delivered-to</strong></li>
<li><strong>return-path</strong></li>
</ul></li>
<li><p>All different priority headers are converted into <strong>priority</strong> with the following values:</p>
<ul>
<li><strong>‘high’</strong></li>
<li><strong>‘normal’</strong></li>
<li><strong>‘low’</strong></li>
</ul></li>
<li><p><strong>references</strong> is a string if only a single reference-id exists or an array if multiple ids exist</p></li>
<li><p><strong>date</strong> value is a Date object</p></li>
<li><p>The following headers are parsed into structured objects, where <em>value</em> property includes the main value as string and <em>params</em> property holds an object of additional arguments as key-value pairs</p>
<ul>
<li><strong>content-type</strong></li>
<li><strong>content-disposition</strong></li>
<li><strong>dkim-signature</strong></li>
</ul></li>
</ol>
<p>Some headers are also automaticaly mime-word decoded</p>
<ul>
<li>all address headers (name parts and punycode encoded domains are converted to unicode)</li>
<li><strong>subject</strong> is converted to unicode</li>
</ul>
<h3 id="attachment-object">attachment object <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#attachment-object"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Attachment objects have the following structure:</p>
<ul>
<li><strong>filename</strong> (if available) file name of the attachment</li>
<li><strong>contentType</strong> MIME type of the message</li>
<li><strong>contentDisposition</strong> content disposition type for the attachment, most probably “attachment”</li>
<li><strong>checksum</strong> a MD5 hash of the message content</li>
<li><strong>size</strong> message size in bytes</li>
<li><strong>headers</strong> a Map value that holds MIME headers for the attachment node</li>
<li><strong>content</strong> a Buffer that contains the attachment contents</li>
<li><strong>contentId</strong> the header value from ‘Content-ID’ (if present)</li>
<li><strong>cid</strong> contentId without < and ></li>
<li><strong>related</strong> if true then this attachment should not be offered for download (at least not in the main attachments list)</li>
</ul>
<h2 id="mailparser">MailParser <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#mailparser"><i class="fa fa-link fa-lg"></i></span></h2>
<p><strong>MailParser</strong> is a lower-level email parsing class. It is a transform stream that takes email source as bytestream for the input and emits data objects for attachments and text contents.</p>
<pre><code class="language-javascript hljs"><span class="hljs-keyword">const</span> MailParser = <span class="hljs-built_in">require</span>(<span class="hljs-string">'mailparser'</span>).MailParser;
<span class="hljs-keyword">let</span> parser = <span class="hljs-keyword">new</span> MailParser()
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<h3 id="event-headers">Event ‘headers’ <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#event-headers"><i class="fa fa-link fa-lg"></i></span></h3>
<p>The parser emits ‘headers’ once message headers have been processed. The headers object is a Map. Different header keys have different kind of values, for example address headers have the address object/array as the value while subject value is string.</p>
<p>Header keys in the Map are lowercase.</p>
<pre><code class="language-javascript hljs">parser.on(<span class="hljs-string">'headers'</span>, headers => {
<span class="hljs-built_in">console</span>.log(headers.get(<span class="hljs-string">'subject'</span>));
});
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<h3 id="event-data">Event ‘data’ <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#event-data"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Event ‘data’ or ‘readable’ emits message content objects. The type of the object can be determine by the <em>type</em> property. Currently there are two kind of data objects</p>
<ul>
<li>‘attachment’ indicates that this object is an attachment</li>
<li>‘text’ indicates that this object includes the html and text parts of the message. This object is emitted once and it includes both values</li>
</ul>
<h3 id="attachment-object-1">attachment object <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#attachment-object-1"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Attachment object is the same as in <em>simpleParser</em> except that <em>content</em> is not a buffer but a stream. Additionally there’s a method <strong>release()</strong> that must be called once you have processed the attachment. The property <em>related</em> is set after message processing is ended, so at the <em>data</em> event this value is not yet available.</p>
<pre><code class="language-javascript hljs">parser.on(<span class="hljs-string">'data'</span>, data => {
<span class="hljs-keyword">if</span>(data.type === <span class="hljs-string">'attachment'</span>){
<span class="hljs-built_in">console</span>.log(data.filename);
data.content.pipe(process.stdout);
data.content.on(<span class="hljs-string">'end'</span>, ()=>data.release());
}
});
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<p>If you do not call <strong>release()</strong> then the message processing is paused.</p>
<h3 id="text-object">text object <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#text-object"><i class="fa fa-link fa-lg"></i></span></h3>
<p>Text object has the following keys:</p>
<ul>
<li><strong>text</strong> includes the plaintext version of the message. Is set if the message has at least one ‘text/plain’ node</li>
<li><strong>html</strong> includes the HTML version of the message. Is set if the message has at least one ‘text/html’ node</li>
<li><strong>textAsHtml</strong> includes the plaintext version of the message in HTML format. Is set if the message has at least one ‘text/plain’ node.</li>
</ul>
<pre><code class="language-javascript hljs">parser.on(<span class="hljs-string">'data'</span>, data => {
<span class="hljs-keyword">if</span>(data.type === <span class="hljs-string">'text'</span>){
<span class="hljs-built_in">console</span>.log(data.html);
}
});
</code><span class="copy-to-clipboard" title="Copy to clipboard"></span></pre>
<h2 id="issues">Issues <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#issues"><i class="fa fa-link fa-lg"></i></span></h2>
<p>Charset decoding is handled using <a href="https://github.com/ashtuchkin/iconv-lite" class="highlight">iconv-lite</a> that is missing some charsets, especially some Japanese ones. If required then it would be possible to switch to native iconv bindings with <a href="https://github.com/bnoordhuis/node-iconv" class="highlight">node-iconv</a> to handle these missing charsets but for now this option is not used for easier packaging.</p>
<h2 id="license">License <span class="anchor" data-clipboard-text="https://nodemailer.com/extras/mailparser/#license"><i class="fa fa-link fa-lg"></i></span></h2>
<p><strong>EUPLv1.1</strong></p>
</div>