patramail 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -86
- package/package.json +9 -1
package/README.md
CHANGED
|
@@ -1,74 +1,89 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# PatraMail
|
|
2
4
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
5
|
+
**Transactional emails from a JavaScript object.**
|
|
6
|
+
|
|
7
|
+
Responsive HTML and matching plain text for account emails, events, receipts, and your own messages.
|
|
8
|
+
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
[](package.json)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
|
|
13
|
+
[GitHub repository](https://github.com/sarthak-gupta229/patramail) · [Quick start](#quick-start) · [Templates](#templates) · [Custom emails](#build-a-custom-email) · [API reference](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md)
|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
6
20
|
|
|
7
21
|
```sh
|
|
8
22
|
npm install patramail
|
|
9
23
|
```
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
Generate a password-reset email from an action URL supplied by your app.
|
|
12
26
|
|
|
13
27
|
```js
|
|
14
28
|
const PatraMail = require('patramail');
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
theme: 'default',
|
|
18
|
-
product: {
|
|
19
|
-
name: 'Acme',
|
|
20
|
-
link: 'https://acme.test',
|
|
21
|
-
},
|
|
29
|
+
const mailer = new PatraMail({
|
|
30
|
+
product: { name: 'Acme', link: 'https://acme.test' },
|
|
22
31
|
});
|
|
23
32
|
|
|
24
|
-
const email = {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
action: {
|
|
29
|
-
instructions: 'Confirm your email address to get started.',
|
|
30
|
-
button: {
|
|
31
|
-
color: '#1746a2',
|
|
32
|
-
text: 'Confirm your account',
|
|
33
|
-
link: 'https://acme.test/confirm?token=example',
|
|
34
|
-
},
|
|
35
|
-
},
|
|
36
|
-
outro: 'If you have questions, reply to this email.',
|
|
37
|
-
},
|
|
38
|
-
};
|
|
33
|
+
const email = PatraMail.templates.passwordReset({
|
|
34
|
+
recipient: 'Jane',
|
|
35
|
+
link: 'https://acme.test/reset?token=example',
|
|
36
|
+
});
|
|
39
37
|
|
|
40
|
-
const
|
|
41
|
-
const
|
|
38
|
+
const html = mailer.generate(email);
|
|
39
|
+
const text = mailer.generatePlaintext(email);
|
|
42
40
|
|
|
43
|
-
require('node:fs').writeFileSync('preview.html',
|
|
41
|
+
require('node:fs').writeFileSync('preview.html', html, 'utf8');
|
|
44
42
|
```
|
|
45
43
|
|
|
46
|
-
Open `preview.html` in a browser
|
|
47
|
-
|
|
44
|
+
Open `preview.html` in a browser. PatraMail generates the content. Your email
|
|
45
|
+
transport handles delivery. For both formats and the subject and preheader in
|
|
46
|
+
one call, use the [named `PatraMail` constructor](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md).
|
|
48
47
|
|
|
49
|
-
|
|
48
|
+
## Templates
|
|
49
|
+
|
|
50
|
+
| Password reset | Email verification |
|
|
51
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
|  |  |
|
|
53
|
+
|
|
54
|
+
| Account templates | Event templates |
|
|
55
|
+
| ------------------------------------------ | -------------------------------------------- |
|
|
56
|
+
| `passwordReset` · Reset password | `invitation` · Collect RSVPs |
|
|
57
|
+
| `emailVerification` · Verify email address | `confirmation` · Confirm a registration |
|
|
58
|
+
| `dashboardWelcome` · Go to dashboard | `reminder` · Send details before the event |
|
|
59
|
+
| | `update` · Announce a change |
|
|
60
|
+
| | `cancellation` · Notify attendees |
|
|
61
|
+
| | `followUp` · Share resources after the event |
|
|
62
|
+
|
|
63
|
+
Account templates take an action URL from your app. Event templates can include
|
|
64
|
+
a date, location, and action button. All nine generate HTML and plain text.
|
|
65
|
+
[Account template options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md#account-templates) · [Event template options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/events.md)
|
|
50
66
|
|
|
51
67
|
## Build a custom email
|
|
52
68
|
|
|
53
|
-
Pass your own `body` to
|
|
54
|
-
|
|
55
|
-
|
|
69
|
+
Pass your own `body` to create a message from scratch. The default constructor
|
|
70
|
+
supports the Mailgen-style `body.action`, `generate()`, and
|
|
71
|
+
`generatePlaintext()` workflow. Choose the built-in light or dark theme,
|
|
72
|
+
or pass custom colors and typography.
|
|
56
73
|
|
|
57
74
|
```js
|
|
58
75
|
const PatraMail = require('patramail');
|
|
59
76
|
const mailer = new PatraMail({
|
|
60
|
-
theme: { brand: '#30564b', radius: '8px' },
|
|
61
77
|
product: { name: 'Acme', link: 'https://acme.test' },
|
|
78
|
+
theme: { brand: '#30564b', radius: '8px' },
|
|
62
79
|
});
|
|
63
80
|
|
|
64
81
|
const email = {
|
|
65
|
-
subject: 'Your monthly statement is ready',
|
|
66
|
-
preheader: 'Review your statement and billing settings.',
|
|
67
82
|
body: {
|
|
68
83
|
title: 'Your statement is ready',
|
|
69
84
|
intro: [
|
|
70
85
|
'Your monthly statement is available.',
|
|
71
|
-
'
|
|
86
|
+
'View or download it in your account.',
|
|
72
87
|
],
|
|
73
88
|
action: [
|
|
74
89
|
{
|
|
@@ -90,71 +105,57 @@ const html = mailer.generate(email);
|
|
|
90
105
|
const text = mailer.generatePlaintext(email);
|
|
91
106
|
```
|
|
92
107
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
## Account and event templates
|
|
97
|
-
|
|
98
|
-
Use `templates.passwordReset`, `templates.emailVerification`, or
|
|
99
|
-
`templates.dashboardWelcome` for common account emails. Each accepts the
|
|
100
|
-
action URL from your application and generates matching HTML and text.
|
|
101
|
-
See the [account template example](docs/api.md#account-templates).
|
|
102
|
-
|
|
103
|
-
Choose from invitation, registration confirmation, reminder, event update,
|
|
104
|
-
cancellation, and follow-up templates. Each supplies event copy, a color
|
|
105
|
-
palette, and an optional action button. See the
|
|
106
|
-
[event template guide](docs/events.md) for a complete example.
|
|
107
|
-
|
|
108
|
-
Use `const { PatraMail } = require('patramail')` when you want the
|
|
109
|
-
combined `{ html, text, subject, preheader }` result in one call.
|
|
110
|
-
See the [API reference](docs/api.md).
|
|
108
|
+
Add a preheader, product logo, or receipt table using the [input schema](https://github.com/sarthak-gupta229/patramail/blob/main/docs/input-schema.md).
|
|
109
|
+
PatraMail escapes user content by default and validates action URLs.
|
|
110
|
+
[Theme options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/themes.md) · [Mailgen-style API](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md#mailgen-style-usage)
|
|
111
111
|
|
|
112
112
|
## Send with Nodemailer
|
|
113
113
|
|
|
114
|
-
Install Nodemailer
|
|
115
|
-
|
|
114
|
+
Install Nodemailer with `npm install nodemailer`. Pass the generated content
|
|
115
|
+
to your transport inside an async function.
|
|
116
116
|
|
|
117
117
|
```js
|
|
118
118
|
const nodemailer = require('nodemailer');
|
|
119
|
+
|
|
119
120
|
const transport = nodemailer.createTransport(process.env.SMTP_URL);
|
|
120
121
|
await transport.sendMail({
|
|
121
122
|
from: process.env.MAIL_FROM,
|
|
122
123
|
to: process.env.MAIL_TO,
|
|
123
|
-
subject: '
|
|
124
|
-
html
|
|
125
|
-
text
|
|
124
|
+
subject: 'Reset your Acme password',
|
|
125
|
+
html,
|
|
126
|
+
text,
|
|
126
127
|
});
|
|
127
128
|
```
|
|
128
129
|
|
|
129
|
-
Set `SMTP_URL
|
|
130
|
-
|
|
130
|
+
Set `SMTP_URL`, `MAIL_FROM`, and `MAIL_TO` for your provider.
|
|
131
|
+
The [runnable Nodemailer example](https://github.com/sarthak-gupta229/patramail/blob/main/examples/with-nodemailer.js) can also print
|
|
132
|
+
a complete MIME message locally.
|
|
131
133
|
|
|
132
|
-
##
|
|
134
|
+
## Preview and develop
|
|
133
135
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
136
|
+
```sh
|
|
137
|
+
npm ci
|
|
138
|
+
npm run preview
|
|
139
|
+
npm test
|
|
140
|
+
npm run lint
|
|
141
|
+
```
|
|
139
142
|
|
|
140
|
-
|
|
143
|
+
Open the generated files in `preview/`. The repository also includes runnable
|
|
144
|
+
[account](https://github.com/sarthak-gupta229/patramail/blob/main/examples/account.js), [event](https://github.com/sarthak-gupta229/patramail/blob/main/examples/events.js),
|
|
145
|
+
[receipt](https://github.com/sarthak-gupta229/patramail/blob/main/examples/receipt.js), and [Mailgen-style](https://github.com/sarthak-gupta229/patramail/blob/main/examples/mailgen-style/index.js)
|
|
146
|
+
examples. To update HTML snapshots intentionally, run
|
|
147
|
+
`UPDATE_SNAPSHOTS=1 npm test` and review the diffs.
|
|
141
148
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
checks. Inbox verification is still pending for Gmail, Outlook desktop and web,
|
|
145
|
-
Apple Mail, and a mobile email client.
|
|
149
|
+
<details>
|
|
150
|
+
<summary>Email-client compatibility</summary>
|
|
146
151
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
Keep transactional tables narrow when targeting those clients. [Can I email overflow results](https://www.caniemail.com/features/css-overflow/)
|
|
152
|
+
Chrome previews verified desktop light and dark layouts and the 375px receipt
|
|
153
|
+
layout. Real inbox verification is pending for Gmail, Outlook, Apple Mail,
|
|
154
|
+
and mobile email clients.
|
|
151
155
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
a service that renders the supported clients.
|
|
156
|
+
Classic Outlook may show square corners. Dark-mode recoloring and wide-table
|
|
157
|
+
scrolling vary by client. [Dark-mode support](https://www.caniemail.com/features/css-at-media-prefers-color-scheme/) · [Overflow support](https://www.caniemail.com/features/css-overflow/)
|
|
155
158
|
|
|
156
|
-
|
|
159
|
+
</details>
|
|
157
160
|
|
|
158
|
-
|
|
159
|
-
markup intentionally, run `UPDATE_SNAPSHOTS=1 npm test` and review the
|
|
160
|
-
resulting diffs in `test/snapshots/`.
|
|
161
|
+
[Changelog](https://github.com/sarthak-gupta229/patramail/blob/main/CHANGELOG.md) · [MIT License](https://github.com/sarthak-gupta229/patramail/blob/main/LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "patramail",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Generate transactional email HTML and plain text from structured input",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"scripts": {
|
|
@@ -20,5 +20,13 @@
|
|
|
20
20
|
"devDependencies": {
|
|
21
21
|
"eslint": "8.57.1",
|
|
22
22
|
"prettier": "3.8.5"
|
|
23
|
+
},
|
|
24
|
+
"repository": {
|
|
25
|
+
"type": "git",
|
|
26
|
+
"url": "git+https://github.com/sarthak-gupta229/patramail.git"
|
|
27
|
+
},
|
|
28
|
+
"homepage": "https://github.com/sarthak-gupta229/patramail#readme",
|
|
29
|
+
"bugs": {
|
|
30
|
+
"url": "https://github.com/sarthak-gupta229/patramail/issues"
|
|
23
31
|
}
|
|
24
32
|
}
|