@postalsys/ee-client 1.3.2 → 1.3.3
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 +162 -113
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
# @postalsys/ee-client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Client library for [EmailEngine](https://emailengine.app/) that works in both the browser and Node.js.
|
|
4
|
+
|
|
5
|
+
It wraps the EmailEngine REST API (`/v1/account/...`) so you can list folders, read and search messages, change flags, move and delete messages, download attachments, and send mail. When you also give it a DOM element, it renders a complete, self-contained webmail interface (folder tree, paginated message list, message viewer, compose modal, dark mode) into that element.
|
|
6
|
+
|
|
7
|
+
This is the same client that powers the built-in message browser in the EmailEngine admin UI.
|
|
8
|
+
|
|
9
|
+
## About EmailEngine
|
|
10
|
+
|
|
11
|
+
[EmailEngine](https://emailengine.app/) is a headless email client application that exposes IMAP, SMTP, Gmail API, and Microsoft Graph API accounts through a single unified REST API and webhooks. This library talks to that REST API - you need a running EmailEngine instance to use it.
|
|
12
|
+
|
|
13
|
+
- Website: https://emailengine.app/
|
|
14
|
+
- API reference: https://api.emailengine.app/
|
|
15
|
+
- Documentation: https://docs.emailengine.app/
|
|
16
|
+
|
|
17
|
+
Note that EmailEngine (the server) is commercial software and requires a subscription; this client library is MIT-licensed.
|
|
4
18
|
|
|
5
19
|
## Installation
|
|
6
20
|
|
|
@@ -8,193 +22,228 @@ EmailEngine client library for browser and Node.js applications.
|
|
|
8
22
|
npm install @postalsys/ee-client
|
|
9
23
|
```
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
This package is **ES modules only** (`"type": "module"`). Import it with `import`; `require()` will not work.
|
|
12
26
|
|
|
13
|
-
|
|
14
|
-
npm install node-fetch
|
|
15
|
-
```
|
|
27
|
+
It has **no runtime dependencies** and uses the platform `fetch`:
|
|
16
28
|
|
|
17
|
-
|
|
29
|
+
- In the browser and on Node.js 18+, the global `fetch` is used automatically.
|
|
30
|
+
- On older Node.js (14-17), install [`node-fetch`](https://www.npmjs.com/package/node-fetch) as a fallback:
|
|
18
31
|
|
|
19
|
-
|
|
32
|
+
```bash
|
|
33
|
+
npm install node-fetch
|
|
34
|
+
```
|
|
20
35
|
|
|
21
|
-
|
|
22
|
-
import { EmailEngineClient } from '@postalsys/ee-client';
|
|
36
|
+
## Quick start
|
|
23
37
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
38
|
+
### Browser (embedded webmail UI)
|
|
39
|
+
|
|
40
|
+
Pass a `container` element and the client renders a full webmail UI into it and loads the inbox automatically:
|
|
41
|
+
|
|
42
|
+
```html
|
|
43
|
+
<div id="email-client" style="height: 600px;"></div>
|
|
44
|
+
<script type="module">
|
|
45
|
+
import { EmailEngineClient } from '@postalsys/ee-client';
|
|
46
|
+
|
|
47
|
+
const client = new EmailEngineClient({
|
|
48
|
+
apiUrl: 'https://your-emailengine-server.example.com',
|
|
49
|
+
account: 'your-account-id',
|
|
50
|
+
accessToken: 'your-access-token',
|
|
51
|
+
container: document.getElementById('email-client')
|
|
52
|
+
});
|
|
53
|
+
</script>
|
|
31
54
|
```
|
|
32
55
|
|
|
33
|
-
|
|
56
|
+
Because the browser talks to EmailEngine directly, use a short-lived, account-scoped token here (see [Authentication](#authentication)) - never a root or admin token.
|
|
57
|
+
|
|
58
|
+
### Node.js (API client, no UI)
|
|
59
|
+
|
|
60
|
+
Omit `container` to use the client purely as an API wrapper:
|
|
34
61
|
|
|
35
62
|
```javascript
|
|
36
63
|
import { EmailEngineClient } from '@postalsys/ee-client';
|
|
37
64
|
|
|
38
|
-
// Create client for API-only usage
|
|
39
65
|
const client = new EmailEngineClient({
|
|
40
|
-
apiUrl: 'https://your-emailengine-server.com',
|
|
66
|
+
apiUrl: 'https://your-emailengine-server.example.com',
|
|
41
67
|
account: 'your-account-id',
|
|
42
68
|
accessToken: 'your-access-token'
|
|
43
69
|
});
|
|
44
70
|
|
|
45
|
-
//
|
|
71
|
+
// List folders
|
|
46
72
|
const folders = await client.loadFolders();
|
|
47
73
|
|
|
48
74
|
// Load messages from INBOX
|
|
49
|
-
const { messages } = await client.loadMessages('INBOX');
|
|
75
|
+
const { messages, nextPageCursor } = await client.loadMessages('INBOX');
|
|
50
76
|
|
|
51
|
-
// Load a
|
|
77
|
+
// Load a single message (its HTML is returned pre-processed for safe display)
|
|
52
78
|
const message = await client.loadMessage(messages[0].id);
|
|
79
|
+
|
|
80
|
+
// Send a plain-text message
|
|
81
|
+
await client.sendMessage('user@example.com', 'Hello', 'Sent from ee-client');
|
|
82
|
+
|
|
83
|
+
// Release the keep-alive timer when done (see destroy() below)
|
|
84
|
+
client.destroy();
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Authentication
|
|
88
|
+
|
|
89
|
+
Every request is sent to EmailEngine with an `Authorization: Bearer <accessToken>` header. Tokens are scoped to a single account, so create one token per account you expose. There are two kinds of tokens you can pass as `accessToken`:
|
|
90
|
+
|
|
91
|
+
### Access tokens
|
|
92
|
+
|
|
93
|
+
Provision a long-lived, account-scoped access token with the `api` scope through the EmailEngine admin UI, or via the API:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
curl -XPOST "https://your-emailengine-server.example.com/v1/token" \
|
|
97
|
+
-H "Authorization: Bearer <root-token>" \
|
|
98
|
+
-H "Content-Type: application/json" \
|
|
99
|
+
-d '{
|
|
100
|
+
"account": "your-account-id",
|
|
101
|
+
"description": "Webmail client",
|
|
102
|
+
"scopes": ["api"]
|
|
103
|
+
}'
|
|
53
104
|
```
|
|
54
105
|
|
|
55
|
-
|
|
106
|
+
The response contains a `token` string to use as `accessToken`. Keep root tokens on your server; only hand an account-scoped `api` token to the browser.
|
|
107
|
+
|
|
108
|
+
### Session tokens (`sess_...`)
|
|
109
|
+
|
|
110
|
+
EmailEngine can also mint short-lived, session-bound tokens whose value starts with `sess_` (this is how its own built-in message browser is embedded). These expire quickly on inactivity. When the client detects a `sess_` token, it automatically pings `GET /v1/account/{account}` after about five minutes of inactivity to keep the token alive. Call [`destroy()`](#destroy-void) to stop that timer when you tear the client down.
|
|
111
|
+
|
|
112
|
+
## Constructor options
|
|
113
|
+
|
|
114
|
+
```javascript
|
|
115
|
+
new EmailEngineClient(options);
|
|
116
|
+
```
|
|
56
117
|
|
|
57
|
-
|
|
118
|
+
| Option | Type | Default | Description |
|
|
119
|
+
| --------------- | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| `account` | `string` | (required) | EmailEngine account identifier. |
|
|
121
|
+
| `apiUrl` | `string` | `http://127.0.0.1:3000` | Base URL of your EmailEngine instance. |
|
|
122
|
+
| `accessToken` | `string` | - | Bearer token for API authentication. |
|
|
123
|
+
| `container` | `HTMLElement` | - | DOM element to render the webmail UI into. Omit for API-only use. |
|
|
124
|
+
| `pageSize` | `number` | `20` | Messages per page. A saved value in `localStorage` takes precedence. |
|
|
125
|
+
| `confirmMethod` | `function` | browser `confirm()` | Custom confirm dialog, `(message, title, cancelText, okText)`. May be sync or async; returns a boolean. |
|
|
126
|
+
| `alertMethod` | `function` | browser `alert()` | Custom alert dialog, `(message, title, cancelText, okText)` where `cancelText` is `null`. |
|
|
58
127
|
|
|
59
|
-
|
|
60
|
-
- `account` (string, required): Account identifier
|
|
61
|
-
- `accessToken` (string, optional): Access token for authentication
|
|
62
|
-
- `container` (HTMLElement, optional): DOM container for UI components (browser only)
|
|
63
|
-
- `confirmMethod` (function, optional): Custom confirm dialog method. Receives `(message, title, cancelText, okText)` parameters. Can be sync or async. Defaults to browser's `confirm()` with standard parameters.
|
|
64
|
-
- `alertMethod` (function, optional): Custom alert dialog method. Receives `(message, title, cancelText, okText)` parameters where `cancelText` is `null` for alerts. Can be sync or async. Defaults to browser's `alert()` with standard parameters.
|
|
128
|
+
UI rendering, the compose modal, and dark mode only activate when a `container` is supplied. In a non-browser environment the UI is skipped and the instance behaves as a plain API client.
|
|
65
129
|
|
|
66
|
-
|
|
130
|
+
### Factory helper
|
|
131
|
+
|
|
132
|
+
`createEmailEngineClient()` is a convenience wrapper that also accepts a container element or an element id, and validates that `account` is present:
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
import { createEmailEngineClient } from '@postalsys/ee-client';
|
|
136
|
+
|
|
137
|
+
// From an options object with a containerId
|
|
138
|
+
const client = createEmailEngineClient({
|
|
139
|
+
apiUrl: 'https://your-emailengine-server.example.com',
|
|
140
|
+
account: 'your-account-id',
|
|
141
|
+
accessToken: 'your-access-token',
|
|
142
|
+
containerId: 'email-client'
|
|
143
|
+
});
|
|
144
|
+
```
|
|
67
145
|
|
|
68
|
-
|
|
146
|
+
## Methods
|
|
69
147
|
|
|
70
|
-
|
|
148
|
+
### `loadFolders(): Promise<Folder[]>`
|
|
71
149
|
|
|
72
|
-
Load all folders/mailboxes for the account.
|
|
150
|
+
Load all folders/mailboxes for the account. Renders the folder tree when a container is set.
|
|
73
151
|
|
|
74
|
-
|
|
152
|
+
### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
|
|
75
153
|
|
|
76
|
-
Load messages from a
|
|
154
|
+
Load a page of messages from a folder. Pass `nextPageCursor` / `prevPageCursor` from a previous response to paginate. Resolves to `{ messages, nextPageCursor, prevPageCursor }`.
|
|
77
155
|
|
|
78
|
-
|
|
156
|
+
### `loadMessage(messageId: string): Promise<Message>`
|
|
79
157
|
|
|
80
|
-
Load a
|
|
158
|
+
Load a single message. HTML is requested with `webSafeHtml=true`, so EmailEngine returns it pre-processed with inline images embedded for safe display, and the message is marked as seen.
|
|
81
159
|
|
|
82
|
-
|
|
160
|
+
### `markAsRead(messageId: string, seen?: boolean): Promise<boolean>`
|
|
83
161
|
|
|
84
|
-
|
|
162
|
+
Add or remove the `\Seen` flag. Pass `false` to mark as unread.
|
|
85
163
|
|
|
86
|
-
|
|
164
|
+
### `deleteMessage(messageId: string): Promise<boolean>`
|
|
87
165
|
|
|
88
|
-
Delete a message.
|
|
166
|
+
Delete a message (EmailEngine moves it to Trash, or removes it if already in Trash).
|
|
89
167
|
|
|
90
|
-
|
|
168
|
+
### `moveMessage(messageId: string, targetPath: string): Promise<boolean>`
|
|
91
169
|
|
|
92
170
|
Move a message to another folder.
|
|
93
171
|
|
|
94
|
-
|
|
172
|
+
### `sendMessage(to, subject, text): Promise<object>`
|
|
95
173
|
|
|
96
|
-
Send a
|
|
174
|
+
Send a plain-text email. `to` may be:
|
|
97
175
|
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
176
|
+
- a string address: `'user@example.com'`
|
|
177
|
+
- an object: `{ name: 'John Doe', address: 'john@example.com' }`
|
|
178
|
+
- an array of strings and/or objects for multiple recipients
|
|
101
179
|
|
|
102
|
-
|
|
180
|
+
Resolves to EmailEngine's submit response.
|
|
103
181
|
|
|
104
|
-
|
|
182
|
+
### `downloadAttachment(attachmentId: string, suggestedFilename?: string): Promise<void>`
|
|
105
183
|
|
|
106
|
-
|
|
184
|
+
Browser only. Fetch an attachment and trigger a download, using the filename from the `Content-Disposition` header when available.
|
|
107
185
|
|
|
108
|
-
|
|
186
|
+
### `downloadOriginalMessage(messageId: string, subject?: string): Promise<void>`
|
|
109
187
|
|
|
110
|
-
|
|
111
|
-
- Message list with pagination
|
|
112
|
-
- Message viewer with actions (mark as read/unread, delete, move)
|
|
113
|
-
- Responsive design
|
|
114
|
-
- Dark mode support with persistent preference
|
|
188
|
+
Browser only. Download the raw message source as an `.eml` file.
|
|
115
189
|
|
|
116
|
-
|
|
117
|
-
<div id="email-client" style="height: 600px;"></div>
|
|
118
|
-
<script type="module">
|
|
119
|
-
import { EmailEngineClient } from '@postalsys/ee-client';
|
|
190
|
+
### `destroy(): void`
|
|
120
191
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
accessToken: 'your-access-token',
|
|
125
|
-
container: document.getElementById('email-client'),
|
|
126
|
-
// Optional: Custom confirm dialog
|
|
127
|
-
confirmMethod: async message => {
|
|
128
|
-
return await myCustomDialog.confirm(message);
|
|
129
|
-
}
|
|
130
|
-
});
|
|
131
|
-
</script>
|
|
132
|
-
```
|
|
192
|
+
Clean up the instance and clear the `sess_` token keep-alive interval. Always call this when you are finished with a client (for example when unmounting the UI) to avoid a leaked timer.
|
|
193
|
+
|
|
194
|
+
## Browser UI
|
|
133
195
|
|
|
134
|
-
|
|
196
|
+
When a `container` is provided the client builds a full webmail interface:
|
|
135
197
|
|
|
136
|
-
|
|
198
|
+
- Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
|
|
199
|
+
- Paginated message list with a selectable page size (persisted to `localStorage`)
|
|
200
|
+
- Message viewer with mark read/unread, delete, move-to-folder, download original, and attachment downloads
|
|
201
|
+
- Compose modal (floating button) for sending plain-text mail
|
|
202
|
+
- Dark mode toggle with the preference persisted to `localStorage`
|
|
203
|
+
|
|
204
|
+
### Custom dialogs
|
|
205
|
+
|
|
206
|
+
Provide `confirmMethod` and `alertMethod` to route confirmations and alerts through your own modal system instead of the browser defaults - useful when integrating with a UI framework:
|
|
137
207
|
|
|
138
208
|
```javascript
|
|
139
209
|
const client = new EmailEngineClient({
|
|
140
|
-
apiUrl: 'https://your-emailengine-server.com',
|
|
210
|
+
apiUrl: 'https://your-emailengine-server.example.com',
|
|
141
211
|
account: 'your-account-id',
|
|
142
212
|
accessToken: 'your-access-token',
|
|
143
213
|
container: document.getElementById('email-client'),
|
|
144
214
|
|
|
145
|
-
// Custom alert method
|
|
146
215
|
alertMethod: async (message, title, cancelText, okText) => {
|
|
147
|
-
return await MyModal.alert({
|
|
148
|
-
title: title, // e.g., "Success", "Error", "Notice"
|
|
149
|
-
message: message,
|
|
150
|
-
okButton: okText // e.g., "OK"
|
|
151
|
-
// cancelText is null for alerts
|
|
152
|
-
});
|
|
216
|
+
return await MyModal.alert({ title, message, okButton: okText });
|
|
153
217
|
},
|
|
154
218
|
|
|
155
|
-
// Custom confirm method
|
|
156
219
|
confirmMethod: async (message, title, cancelText, okText) => {
|
|
157
|
-
return await MyModal.confirm({
|
|
158
|
-
title: title, // e.g., "Delete Message", "Confirm"
|
|
159
|
-
message: message,
|
|
160
|
-
cancelButton: cancelText, // e.g., "Cancel"
|
|
161
|
-
okButton: okText // e.g., "Delete", "OK"
|
|
162
|
-
});
|
|
220
|
+
return await MyModal.confirm({ title, message, cancelButton: cancelText, okButton: okText });
|
|
163
221
|
}
|
|
164
222
|
});
|
|
165
223
|
```
|
|
166
224
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
Both methods receive the same parameters:
|
|
170
|
-
|
|
171
|
-
- `message` (string): The message to display
|
|
172
|
-
- `title` (string): Dialog title (defaults: "Confirm" for confirm, "Notice" for alert)
|
|
173
|
-
- `cancelText` (string|null): Cancel button text ("Cancel" for confirm, `null` for alert)
|
|
174
|
-
- `okText` (string): OK/action button text (defaults: "OK")
|
|
225
|
+
Both methods receive the same arguments:
|
|
175
226
|
|
|
176
|
-
|
|
227
|
+
- `message` (string): text to display
|
|
228
|
+
- `title` (string): dialog title (defaults: `Confirm` / `Notice`)
|
|
229
|
+
- `cancelText` (string | null): cancel button text (`Cancel` for confirm, `null` for alert)
|
|
230
|
+
- `okText` (string): confirm/OK button text (default `OK`)
|
|
177
231
|
|
|
178
|
-
The
|
|
232
|
+
The client uses contextual titles such as `Delete Message`, `Validation Error`, `Success`, `Send Error`, and `Download Error`. `confirmMethod` should return a boolean (or a promise for one); `alertMethod` may be sync or async.
|
|
179
233
|
|
|
180
|
-
|
|
181
|
-
- **Success messages**: `alertMethod(message, "Success", null, "OK")`
|
|
182
|
-
- **Send errors**: `alertMethod(message, "Send Error", null, "OK")`
|
|
183
|
-
- **Download errors**: `alertMethod(message, "Download Error", null, "OK")`
|
|
184
|
-
- **Delete confirmation**: `confirmMethod(message, "Delete Message", "Cancel", "Delete")`
|
|
234
|
+
## Security
|
|
185
235
|
|
|
186
|
-
|
|
236
|
+
This library renders attacker-controlled email content, so it is careful about HTML injection:
|
|
187
237
|
|
|
188
|
-
|
|
238
|
+
- All untrusted values (subjects, addresses, names, filenames, folder names) are HTML-escaped before being written to the DOM.
|
|
239
|
+
- The one intentional raw-HTML sink is the message body itself. The client fetches it with EmailEngine's `webSafeHtml` option so the HTML arrives already pre-processed for safe embedding.
|
|
189
240
|
|
|
190
|
-
|
|
241
|
+
Do not disable escaping or add new raw-HTML sinks when extending the UI.
|
|
191
242
|
|
|
192
|
-
|
|
193
|
-
- **Persistent Preference**: Dark mode preference is saved to localStorage and restored on page reload
|
|
194
|
-
- **Complete Theme**: All UI components are styled for optimal readability in both light and dark modes
|
|
243
|
+
## TypeScript
|
|
195
244
|
|
|
196
|
-
|
|
245
|
+
Type declarations ship with the package (`index.d.ts`), so `EmailEngineClient`, `createEmailEngineClient`, and the exported interfaces (`Folder`, `Message`, `MessageListResponse`, `EmailEngineClientOptions`, and others) are typed out of the box - no `@types` package needed.
|
|
197
246
|
|
|
198
247
|
## License
|
|
199
248
|
|
|
200
|
-
MIT
|
|
249
|
+
MIT (c) Postal Systems OÜ
|