@postalsys/ee-client 1.11.2 → 2.0.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 +67 -42
- package/index.d.ts +96 -17
- package/index.js +1709 -637
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -77,8 +77,8 @@ const { messages, nextPageCursor } = await client.loadMessages('INBOX');
|
|
|
77
77
|
// Load a single message (its HTML is returned pre-processed for safe display)
|
|
78
78
|
const message = await client.loadMessage(messages[0].id);
|
|
79
79
|
|
|
80
|
-
// Send a
|
|
81
|
-
await client.sendMessage('user@example.com', 'Hello', 'Sent from ee-client');
|
|
80
|
+
// Send a message
|
|
81
|
+
await client.sendMessage({ to: 'user@example.com', subject: 'Hello', text: 'Sent from ee-client' });
|
|
82
82
|
|
|
83
83
|
// Release the keep-alive timer when done (see destroy() below)
|
|
84
84
|
client.destroy();
|
|
@@ -115,21 +115,24 @@ EmailEngine can also mint short-lived, session-bound tokens whose value starts w
|
|
|
115
115
|
new EmailEngineClient(options);
|
|
116
116
|
```
|
|
117
117
|
|
|
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`.
|
|
127
|
-
| `darkMode` | `boolean` | stored preference | Initial dark mode. Overrides the preference stored by the builtin toggle.
|
|
128
|
-
| `showDarkModeToggle` | `boolean` | `true` | Render the builtin dark mode toggle. Set `false` when the host application drives the mode through `client.setDarkMode(enabled)` (for example in sync with its own theme switch).
|
|
129
|
-
| `styleNonce` | `string` | none | Nonce set on the `<style>` elements the widget creates (its own stylesheet and the one inside the message body's shadow root). Pass the page's Content-Security-Policy nonce when `style-src-elem` allows no inline stylesheet without one.
|
|
130
|
-
| `message` | `string` | none | EmailEngine message ID to open on startup instead of the inbox. The folder holding it is listed next to it (the inbox for Gmail API accounts, which report no folder). Use it to deep-link into one message.
|
|
131
|
-
| `onNavigate` | `function` | none | Called with `{ path, messageId }` whenever the open folder or message changes, so the host page can keep its address bar in step (`history.replaceState`). `messageId` is `null` when no message is open.
|
|
132
|
-
| `maxAttachmentSize` | `number` | `25 MB` | Total size limit, in bytes, of the files attached in the compose form. Files are sent base64 encoded in one JSON request, so keep it under EmailEngine's API body limit.
|
|
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, or `null` when the dialog was dismissed (see below). |
|
|
126
|
+
| `alertMethod` | `function` | browser `alert()` | Custom alert dialog, `(message, title, cancelText, okText)` where `cancelText` is `null`. |
|
|
127
|
+
| `darkMode` | `boolean` | stored preference | Initial dark mode. Overrides the preference stored by the builtin toggle. |
|
|
128
|
+
| `showDarkModeToggle` | `boolean` | `true` | Render the builtin dark mode toggle. Set `false` when the host application drives the mode through `client.setDarkMode(enabled)` (for example in sync with its own theme switch). |
|
|
129
|
+
| `styleNonce` | `string` | none | Nonce set on the `<style>` elements the widget creates (its own stylesheet and the one inside the message body's shadow root). Pass the page's Content-Security-Policy nonce when `style-src-elem` allows no inline stylesheet without one. |
|
|
130
|
+
| `message` | `string` | none | EmailEngine message ID to open on startup instead of the inbox. The folder holding it is listed next to it (the inbox for Gmail API accounts, which report no folder). Use it to deep-link into one message. |
|
|
131
|
+
| `onNavigate` | `function` | none | Called with `{ path, messageId }` whenever the open folder or message changes, so the host page can keep its address bar in step (`history.replaceState`). `messageId` is `null` when no message is open. |
|
|
132
|
+
| `maxAttachmentSize` | `number` | `25 MB` | Total size limit, in bytes, of the files attached in the compose form. Files are sent base64 encoded in one JSON request, so keep it under EmailEngine's API body limit. |
|
|
133
|
+
| `onMessageSent` | `function` | none | Called with EmailEngine's response whenever a message, or a stored draft, is queued for delivery, from the UI or `sendMessage()` / `submitDraft()`. |
|
|
134
|
+
| `onDraftSaved` | `function` | none | Called with EmailEngine's upload response whenever a draft is stored (`saveDraft()`, `updateDraft()` and the compose form). |
|
|
135
|
+
| `onError` | `function` | none | Called with the error and `{ action, description }` whenever a request fails. `action` is `loadFolders`, `loadMessages`, `loadMessage`, `markAsRead`, `delete`, `move`, `send`, `saveDraft` or `download`. The UI still shows the failure itself. |
|
|
133
136
|
|
|
134
137
|
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.
|
|
135
138
|
|
|
@@ -151,9 +154,13 @@ const client = createEmailEngineClient({
|
|
|
151
154
|
|
|
152
155
|
## Methods
|
|
153
156
|
|
|
154
|
-
### `loadFolders(): Promise<Folder[]>`
|
|
157
|
+
### `loadFolders({ counters }?): Promise<Folder[]>`
|
|
155
158
|
|
|
156
|
-
Load all folders/mailboxes for the account. Renders the folder tree when a container is set.
|
|
159
|
+
Load all folders/mailboxes for the account. Renders the folder tree when a container is set. With `counters: true` each folder carries its message and unread counts in `status` (one IMAP STATUS command per folder); the UI asks for them by default, an API-only client only when told to.
|
|
160
|
+
|
|
161
|
+
### `ready: Promise<boolean>`
|
|
162
|
+
|
|
163
|
+
Resolves once the first view (the folders and a listing, or the deep-linked `message`) has loaded: `true` when it did, `false` when its requests failed and the panes show why. A deep-linked message that cannot be opened does not count as a failure, since the inbox is listed instead. It never rejects, and resolves `true` at once for an API-only client.
|
|
157
164
|
|
|
158
165
|
### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
|
|
159
166
|
|
|
@@ -181,37 +188,40 @@ Move a message to another folder.
|
|
|
181
188
|
|
|
182
189
|
Open a message by its ID and list the folder that holds it, the way the `message` option does on startup. A message that cannot be loaded shows its error in the viewer and the inbox is listed instead.
|
|
183
190
|
|
|
184
|
-
### `sendMessage(
|
|
185
|
-
|
|
186
|
-
Send a plain-text email. Submitting queues the message; EmailEngine delivers it afterwards. `to` may be:
|
|
191
|
+
### `sendMessage(message): Promise<object>`
|
|
187
192
|
|
|
188
|
-
|
|
189
|
-
- an object: `{ name: 'John Doe', address: 'john@example.com' }`
|
|
190
|
-
- an array of strings and/or objects for multiple recipients
|
|
193
|
+
Send an email. Submitting queues the message; EmailEngine delivers it afterwards. `message` is an object:
|
|
191
194
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
- `
|
|
195
|
-
- `attachments`: `
|
|
196
|
-
- `reference`: EmailEngine's submit reference block, `{ message, action, inline, forwardAttachments }`. With it EmailEngine sets the threading headers, quotes the referenced message when `inline` is true, carries its attachments over on a forward with `forwardAttachments`, and flags the original `\Answered` / `$Forwarded` once the message is delivered (IMAP accounts)
|
|
195
|
+
- `to`, `cc`, `bcc`: recipients, each a string address (`'user@example.com'`), an object (`{ name: 'John Doe', address: 'john@example.com' }`) or an array of either
|
|
196
|
+
- `subject`
|
|
197
|
+
- `text`: the plain text part, and `html`: the HTML part (either or both)
|
|
198
|
+
- `attachments`: new files as `{ filename, contentType, content }` with `content` base64 encoded, or attachments of a stored message as `{ reference, filename, contentType }`, where `reference` is the EmailEngine attachment ID. The server fetches a referenced file itself, so forwarding a large file does not pass it through the browser
|
|
199
|
+
- `reference`: EmailEngine's submit reference block, `{ message, action, inline, forwardAttachments }`. With it EmailEngine sets the threading headers, quotes the referenced message when `inline` is true, carries all of its attachments over on a forward with `forwardAttachments`, and flags the original `\Answered` / `$Forwarded` once the message is delivered (IMAP accounts)
|
|
200
|
+
- `headers`: extra headers, for example the `In-Reply-To` and `References` of a reopened draft
|
|
197
201
|
|
|
198
202
|
Resolves to EmailEngine's submit response.
|
|
199
203
|
|
|
200
|
-
### `reply(messageId?, { all }?)`, `forward(messageId?)`, `compose(prefill?)`
|
|
204
|
+
### `reply(messageId?, { all }?)`, `forward(messageId?)`, `compose(prefill?)`, `editDraft(messageId?)`
|
|
205
|
+
|
|
206
|
+
Open the compose form (UI only). `reply()` and `forward()` act on the open message when no ID is given and fill in the recipients, the `Re:` / `Fwd:` subject and the reference; the original is shown under the editor and quoted by EmailEngine when the message is sent. `reply(id, { all: true })` resolves reply-all in the client: the original sender goes in To and the other recipients in Cc, without the account's own address, and the message goes out exactly as the form shows it. A forward lists the original's files as attachments, each of which can be removed. `compose()` opens a blank form and takes `{ to, cc, bcc, subject, text, html }` to prefill it. `editDraft()` opens a stored draft; saving replaces it and sending removes it from Drafts.
|
|
201
207
|
|
|
202
|
-
|
|
208
|
+
When the form already holds unsaved changes, these first ask whether to save them as a draft. They resolve `false` if saving that draft failed and the form stayed as it was, `true` otherwise.
|
|
203
209
|
|
|
204
210
|
### `prepareResponse(msg, action, ownAddress?): object`
|
|
205
211
|
|
|
206
|
-
The recipients, subject and reference of a `'reply'`, `'reply-all'` or `'forward'` of a message, as `reply()` and `forward()` prefill them: `{ to, cc, subject, reference }
|
|
212
|
+
The recipients, subject and reference of a `'reply'`, `'reply-all'` or `'forward'` of a message, as `reply()` and `forward()` prefill them: `{ to, cc, subject, reference }`, plus `attachments` for a forward (the original's files as `{ reference, filename, contentType, size }`). A reply goes to the message's Reply-To, otherwise its sender, or to its recipients when the account sent it. Useful for building a compose UI of your own.
|
|
207
213
|
|
|
208
214
|
### `parseAddressList(value)` / `formatAddressList(list)`
|
|
209
215
|
|
|
210
216
|
Convert between a typed address field (`"Doe, John" <john@example.com>, jane@example.com`) and address entries.
|
|
211
217
|
|
|
212
|
-
### `saveDraft(
|
|
218
|
+
### `saveDraft(message): Promise<object>`
|
|
219
|
+
|
|
220
|
+
Store a message as a draft instead of sending it (`POST /v1/account/{account}/message`). It takes the same message object as `sendMessage()`, and every field may be left out. The message is uploaded to the account's Drafts special-use folder with the `\Draft` flag set and the account's own name and address as the sender, so it can later be delivered with `submitDraft()`. A draft saved with a `reference` keeps the threading headers and the quote. Resolves to EmailEngine's upload response (`{ id, path, uid, ... }`).
|
|
213
221
|
|
|
214
|
-
|
|
222
|
+
### `updateDraft(messageId, message): Promise<object>`
|
|
223
|
+
|
|
224
|
+
Replace a stored draft with a new version. IMAP cannot change a stored message, so the new version is saved first and the old draft removed for good afterwards; attachments the new version references from the old draft are copied before it goes. If the old draft cannot be removed, the new one is kept and the failure only logged. Resolves to the upload response of the new version.
|
|
215
225
|
|
|
216
226
|
### `submitDraft(messageId: string, options?: SubmitDraftOptions): Promise<object>`
|
|
217
227
|
|
|
@@ -235,17 +245,29 @@ Set dark mode from the host application without touching the preference stored b
|
|
|
235
245
|
|
|
236
246
|
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.
|
|
237
247
|
|
|
248
|
+
## Upgrading from 1.x
|
|
249
|
+
|
|
250
|
+
2.0 changes how messages are sent and how compose behaves:
|
|
251
|
+
|
|
252
|
+
- `sendMessage()` and `saveDraft()` take one message object. `sendMessage(to, subject, text, { cc })` becomes `sendMessage({ to, subject, text, cc })`; `saveDraft(to, subject, text, options)` becomes `saveDraft({ to, subject, text, ...options })`. The old form throws a `TypeError` instead of sending a message without its subject and text.
|
|
253
|
+
- `compose()` returns a promise, like `reply()` and `forward()`.
|
|
254
|
+
- A forward attaches the original's files one by one as references (`prepareResponse()` returns them in `attachments`, and its reference has `forwardAttachments: false`).
|
|
255
|
+
- The compose form is a docked panel without a backdrop (class `ee-compose`, formerly `ee-compose-modal`) and writes HTML through its editor; the message textarea is gone. Hosts that styled or scripted the old modal need updating.
|
|
256
|
+
- The folder list is loaded with `counters=true` to show unread counts.
|
|
257
|
+
- New: `updateDraft()` replaces a stored draft, and `editDraft()` opens one in the compose form; `ready` tells when the first view has loaded; `onMessageSent`, `onDraftSaved` and `onError` report outcomes to the host; `loadFolders({ counters })` asks for unread counts.
|
|
258
|
+
|
|
238
259
|
## Browser UI
|
|
239
260
|
|
|
240
261
|
When a `container` is provided the client builds a full webmail interface:
|
|
241
262
|
|
|
242
|
-
- Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
|
|
243
|
-
- Paginated message list with a selectable page size (persisted to `localStorage`)
|
|
263
|
+
- Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive), icons, unread counts and nested folders. The folder list is requested with `counters=true`, which costs one IMAP STATUS command per folder
|
|
264
|
+
- Paginated message list with its position ("1-20 of 45") and a selectable page size (persisted to `localStorage`) in a footer. Unread messages are marked with a dot and bold text; Drafts and Sent list the recipients instead of the sender
|
|
244
265
|
- Message viewer with reply, reply all, forward, mark read/unread, delete, move-to-folder, download original, and attachment downloads
|
|
245
266
|
- Replied and forwarded markers in the list and the viewer, from the `\Answered` and `$Forwarded` flags (IMAP accounts)
|
|
246
|
-
- Draft messages
|
|
267
|
+
- Draft messages open with an "Edit" button that continues the draft in the compose form, and a "Send draft" button that submits it as it is (requires EmailEngine v2.76.0 or later)
|
|
247
268
|
- Quoted thread history collapsed behind a "Show quoted text" control
|
|
248
|
-
- Compose form
|
|
269
|
+
- Compose form docked to the bottom right of the window (full screen on a phone), so the message being answered stays readable. It has a minimal rich text editor (bold, italic, lists, links), To, Cc and Bcc fields that take several addresses, file attachments, and Save draft. A reply's quote is folded behind a "..." control; a forward shows the forwarded message with its header and lists the original's files as attachments that can be removed one by one. Closing a form with unsaved changes asks whether to save them as a draft
|
|
270
|
+
- Folders, messages and attachments are buttons, reachable and usable from the keyboard
|
|
249
271
|
- Dark mode toggle with the preference persisted to `localStorage`
|
|
250
272
|
- Failed requests replace the affected pane's placeholder with an error panel and a Retry button
|
|
251
273
|
|
|
@@ -263,7 +285,9 @@ When opening a message the client scrolls the page only if its top is scrolled o
|
|
|
263
285
|
|
|
264
286
|
### Compose and notices
|
|
265
287
|
|
|
266
|
-
On wide layouts the Compose button sits at the top of the folder pane; in the one-pane layout it is a floating button. Problems with a message (no recipient, an address that is not one, a send the server refused) are shown inside the compose form next to its buttons, and the form keeps what was typed. Outcomes that need no answer ("Message queued for delivery.", "Draft saved
|
|
288
|
+
On wide layouts the Compose button sits at the top of the folder pane; in the one-pane layout it is a floating button. Problems with a message (no recipient, an address that is not one, a send the server refused) are shown inside the compose form next to its buttons, and the form keeps what was typed. Outcomes that need no answer ("Message queued for delivery.", "Draft saved.", "Message moved to Trash.") appear as a short notice at the bottom of the client, which `notify(message)` can show from the host too. `alertMethod` is used for failures outside the form.
|
|
289
|
+
|
|
290
|
+
The editor keeps paragraphs, bold, italic, underline, lists, quotes and `http`, `https` and `mailto` links. Pasted content and reopened drafts are filtered down to those; anything else keeps only its text. A reopened draft of a reply keeps its quote as editable text. A reply to or forward of a message that has no HTML part of its own is quoted into the HTML part by EmailEngine versions after 2.89.0; older versions quote it into the plain text part only.
|
|
267
291
|
|
|
268
292
|
### Dark mode and styled messages
|
|
269
293
|
|
|
@@ -307,14 +331,15 @@ Both methods receive the same arguments:
|
|
|
307
331
|
- `cancelText` (string | null): cancel button text (`Cancel` for confirm, `null` for alert)
|
|
308
332
|
- `okText` (string): confirm/OK button text (default `OK`)
|
|
309
333
|
|
|
310
|
-
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.
|
|
334
|
+
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. When your dialog can be closed without either button (a close button, Escape, a click on the backdrop), have `confirmMethod` return `null` for that: the client then treats the question as unanswered. It matters for "Save the message you are writing as a draft?", whose cancel button discards the message, so a dismissed question keeps the message open instead. The browser's own `confirm()` has no such state, and a host that returns only booleans works as before.
|
|
311
335
|
|
|
312
336
|
## Security
|
|
313
337
|
|
|
314
338
|
This library renders attacker-controlled email content, so it is careful about HTML injection:
|
|
315
339
|
|
|
316
340
|
- All untrusted values (subjects, addresses, names, filenames, folder names) are HTML-escaped before being written to the DOM.
|
|
317
|
-
- 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.
|
|
341
|
+
- 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, and renders it inside a shadow root so host styles and ids cannot reach it.
|
|
342
|
+
- HTML that enters the compose editor (pasted content, a reopened draft, `compose({ html })`) is parsed in an inert document and rebuilt from an allowlist of tags with no attributes except `http`, `https` and `mailto` link targets. The same filter runs on the HTML that is sent.
|
|
318
343
|
|
|
319
344
|
Do not disable escaping or add new raw-HTML sinks when extending the UI.
|
|
320
345
|
|
package/index.d.ts
CHANGED
|
@@ -11,10 +11,13 @@ export interface MessageFlags {
|
|
|
11
11
|
export interface MessageText {
|
|
12
12
|
html?: string;
|
|
13
13
|
plain?: string;
|
|
14
|
+
/** Sizes of the parts as stored; a message without `html` here had no HTML part of its own */
|
|
15
|
+
encodedSize?: { plain?: number; html?: number };
|
|
14
16
|
}
|
|
15
17
|
|
|
16
18
|
export interface MessageStatus {
|
|
17
19
|
messages: number;
|
|
20
|
+
unseen?: number;
|
|
18
21
|
}
|
|
19
22
|
|
|
20
23
|
export interface Folder {
|
|
@@ -36,6 +39,11 @@ export interface Attachment {
|
|
|
36
39
|
filename?: string;
|
|
37
40
|
contentType?: string;
|
|
38
41
|
size?: number;
|
|
42
|
+
/** Size of the attachment as encoded in the message (base64), as EmailEngine reports it */
|
|
43
|
+
encodedSize?: number;
|
|
44
|
+
/** An image the HTML body shows in place; not listed as an attachment */
|
|
45
|
+
embedded?: boolean;
|
|
46
|
+
inline?: boolean;
|
|
39
47
|
}
|
|
40
48
|
|
|
41
49
|
/** One-time passcode of a message, from its OTP-Token header (EmailEngine 2.87+, experimental) */
|
|
@@ -73,9 +81,17 @@ export interface MessageListResponse {
|
|
|
73
81
|
prevPageCursor?: string;
|
|
74
82
|
}
|
|
75
83
|
|
|
84
|
+
/** Where the listed page sits in its folder, when the server reports it */
|
|
85
|
+
export interface ListPosition {
|
|
86
|
+
/** 0-based page number */
|
|
87
|
+
page: number;
|
|
88
|
+
/** Messages in the folder */
|
|
89
|
+
total: number;
|
|
90
|
+
}
|
|
91
|
+
|
|
76
92
|
export type SendRecipient = string | EmailAddress;
|
|
77
93
|
|
|
78
|
-
/** A file to attach
|
|
94
|
+
/** A file to attach: new content, base64 encoded */
|
|
79
95
|
export interface ComposeAttachment {
|
|
80
96
|
filename: string;
|
|
81
97
|
contentType?: string;
|
|
@@ -83,22 +99,43 @@ export interface ComposeAttachment {
|
|
|
83
99
|
content: string;
|
|
84
100
|
}
|
|
85
101
|
|
|
102
|
+
/**
|
|
103
|
+
* An attachment of a stored message, attached by its EmailEngine attachment ID. The server
|
|
104
|
+
* fetches the content itself; filename and contentType are kept on the new message.
|
|
105
|
+
*/
|
|
106
|
+
export interface ReferencedAttachment {
|
|
107
|
+
reference: string;
|
|
108
|
+
filename?: string;
|
|
109
|
+
contentType?: string;
|
|
110
|
+
/** Size in bytes, for display only; not sent */
|
|
111
|
+
size?: number;
|
|
112
|
+
}
|
|
113
|
+
|
|
86
114
|
/** EmailEngine's submit reference block: what the message replies to or forwards */
|
|
87
115
|
export interface MessageReference {
|
|
88
116
|
message: string;
|
|
89
117
|
action: 'reply' | 'reply-all' | 'forward';
|
|
90
118
|
/** Quote the referenced message under the new text */
|
|
91
119
|
inline?: boolean;
|
|
92
|
-
/** Carry the referenced message's attachments over (forward only) */
|
|
120
|
+
/** Carry all of the referenced message's attachments over (forward only) */
|
|
93
121
|
forwardAttachments?: boolean;
|
|
94
122
|
}
|
|
95
123
|
|
|
96
|
-
/**
|
|
97
|
-
export interface
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
124
|
+
/** The message `sendMessage()`, `saveDraft()` and `updateDraft()` take */
|
|
125
|
+
export interface OutgoingMessage {
|
|
126
|
+
to?: SendRecipient | SendRecipient[] | null;
|
|
127
|
+
cc?: SendRecipient | SendRecipient[] | null;
|
|
128
|
+
bcc?: SendRecipient | SendRecipient[] | null;
|
|
129
|
+
subject?: string;
|
|
130
|
+
/** The plain text part */
|
|
131
|
+
text?: string;
|
|
132
|
+
/** The HTML part */
|
|
133
|
+
html?: string;
|
|
134
|
+
attachments?: Array<ComposeAttachment | ReferencedAttachment>;
|
|
135
|
+
/** What the message replies to or forwards; the server adds the threading headers and the quote */
|
|
101
136
|
reference?: MessageReference | null;
|
|
137
|
+
/** Extra headers, e.g. the In-Reply-To and References of a reopened draft */
|
|
138
|
+
headers?: Record<string, string>;
|
|
102
139
|
}
|
|
103
140
|
|
|
104
141
|
/** Recipients, subject and reference of a reply, reply-all or forward, from `prepareResponse()` */
|
|
@@ -107,6 +144,8 @@ export interface PreparedResponse {
|
|
|
107
144
|
cc: EmailAddress[];
|
|
108
145
|
subject: string;
|
|
109
146
|
reference: MessageReference;
|
|
147
|
+
/** A forward's files: the original's attachments as references, one per file */
|
|
148
|
+
attachments?: ReferencedAttachment[];
|
|
110
149
|
}
|
|
111
150
|
|
|
112
151
|
/** Prefill for `compose()`. Address fields take a typed string or address entries */
|
|
@@ -116,6 +155,8 @@ export interface ComposePrefill {
|
|
|
116
155
|
bcc?: string | EmailAddress[];
|
|
117
156
|
subject?: string;
|
|
118
157
|
text?: string;
|
|
158
|
+
/** Rich text for the editor; filtered to paragraphs, emphasis, lists, quotes and http(s)/mailto links */
|
|
159
|
+
html?: string;
|
|
119
160
|
}
|
|
120
161
|
|
|
121
162
|
/** What `onNavigate` is told whenever the open folder or message changes */
|
|
@@ -147,7 +188,13 @@ export interface SubmitDraftOptions {
|
|
|
147
188
|
* `(message, title, cancelText, okText)`; `cancelText` is `null` for alerts.
|
|
148
189
|
* May be synchronous or asynchronous. Confirm handlers should resolve to a boolean.
|
|
149
190
|
*/
|
|
150
|
-
|
|
191
|
+
/** A confirm resolves true for the OK button and false for the cancel button. A host dialog closed without either (its close button, Escape, the backdrop) may resolve null: the client then treats the question as unanswered, which keeps an unsaved message open. */
|
|
192
|
+
export type DialogMethod = (
|
|
193
|
+
message: string,
|
|
194
|
+
title?: string,
|
|
195
|
+
cancelText?: string | null,
|
|
196
|
+
okText?: string
|
|
197
|
+
) => boolean | null | void | Promise<boolean | null | void>;
|
|
151
198
|
|
|
152
199
|
export interface EmailEngineClientOptions {
|
|
153
200
|
apiUrl?: string;
|
|
@@ -170,6 +217,19 @@ export interface EmailEngineClientOptions {
|
|
|
170
217
|
onNavigate?: (state: NavigationState) => void;
|
|
171
218
|
/** Total size limit for files attached in the compose form, in bytes (default 25 MB) */
|
|
172
219
|
maxAttachmentSize?: number;
|
|
220
|
+
/** Called with EmailEngine's response whenever a message or a stored draft is queued for delivery */
|
|
221
|
+
onMessageSent?: (response: any) => void;
|
|
222
|
+
/** Called with EmailEngine's upload response whenever a draft is stored */
|
|
223
|
+
onDraftSaved?: (response: any) => void;
|
|
224
|
+
/** Called whenever a request fails, with what the client was doing */
|
|
225
|
+
onError?: (error: Error, context: ErrorContext) => void;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** What `onError` is told about a failed request */
|
|
229
|
+
export interface ErrorContext {
|
|
230
|
+
action: 'loadFolders' | 'loadMessages' | 'loadMessage' | 'markAsRead' | 'delete' | 'move' | 'send' | 'saveDraft' | 'download';
|
|
231
|
+
/** The failure in words, e.g. "Failed to load the folders" */
|
|
232
|
+
description: string;
|
|
173
233
|
}
|
|
174
234
|
|
|
175
235
|
export declare class EmailEngineClient {
|
|
@@ -190,11 +250,20 @@ export declare class EmailEngineClient {
|
|
|
190
250
|
messages: Message[];
|
|
191
251
|
nextPageCursor: string | null;
|
|
192
252
|
prevPageCursor: string | null;
|
|
253
|
+
listPosition: ListPosition | null;
|
|
254
|
+
/**
|
|
255
|
+
* Resolves once the first view (folders and a listing, or a deep-linked message) has loaded:
|
|
256
|
+
* true when it did, false when its requests failed and the panes show why (a deep-linked
|
|
257
|
+
* message that could not be opened does not count, the inbox is listed instead). Resolves true
|
|
258
|
+
* at once for an API-only client, and false outside a browser.
|
|
259
|
+
*/
|
|
260
|
+
ready: Promise<boolean>;
|
|
193
261
|
|
|
194
262
|
constructor(options?: EmailEngineClientOptions);
|
|
195
263
|
|
|
196
264
|
apiRequest(method: string, endpoint: string, data?: any): Promise<any>;
|
|
197
|
-
|
|
265
|
+
/** Lists the folders; counters adds message and unread counts (default: true when the UI is rendered) */
|
|
266
|
+
loadFolders(options?: { counters?: boolean }): Promise<Folder[]>;
|
|
198
267
|
/** Loads a page of a folder's message list; the open message stays open */
|
|
199
268
|
loadMessages(path: string, cursor?: string | null): Promise<MessageListResponse>;
|
|
200
269
|
/** Closes the open message and lists another folder */
|
|
@@ -206,20 +275,30 @@ export declare class EmailEngineClient {
|
|
|
206
275
|
moveMessage(messageId: string, targetPath: string): Promise<boolean>;
|
|
207
276
|
/** Opens a message by ID and lists the folder that holds it */
|
|
208
277
|
openMessage(messageId: string): Promise<Message | null>;
|
|
209
|
-
|
|
210
|
-
|
|
278
|
+
/** Submits a message for delivery. Since 2.0 it takes one message object */
|
|
279
|
+
sendMessage(message: OutgoingMessage): Promise<any>;
|
|
280
|
+
/** Stores a message in the Drafts folder */
|
|
281
|
+
saveDraft(message: OutgoingMessage): Promise<any>;
|
|
282
|
+
/** Replaces a stored draft: saves the new version, then removes the old one for good */
|
|
283
|
+
updateDraft(messageId: string, message: OutgoingMessage): Promise<any>;
|
|
211
284
|
/** Parses a typed address field ("Name <a@example.com>, b@example.com") into address entries */
|
|
212
285
|
parseAddressList(value: string | null | undefined): EmailAddress[];
|
|
213
286
|
/** Formats address entries for an address field; the reverse of parseAddressList() */
|
|
214
287
|
formatAddressList(list: EmailAddress | EmailAddress[] | null | undefined): string;
|
|
215
288
|
/** Recipients, subject and reference for answering msg; ownAddress is left out of the recipients */
|
|
216
289
|
prepareResponse(msg: Message, action: 'reply' | 'reply-all' | 'forward', ownAddress?: string | null): PreparedResponse;
|
|
217
|
-
/**
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
290
|
+
/**
|
|
291
|
+
* Opens the compose form, optionally prefilled. Like reply(), forward() and editDraft() it
|
|
292
|
+
* needs the UI, and resolves false when an unsaved message stayed open instead (the user chose
|
|
293
|
+
* to save it as a draft and saving failed), true otherwise.
|
|
294
|
+
*/
|
|
295
|
+
compose(prefill?: ComposePrefill): Promise<boolean>;
|
|
296
|
+
/** Opens the compose form as a reply to a message, the open one by default */
|
|
297
|
+
reply(messageId?: string | null, options?: { all?: boolean }): Promise<boolean>;
|
|
298
|
+
/** Opens the compose form to forward a message, the open one by default */
|
|
299
|
+
forward(messageId?: string | null): Promise<boolean>;
|
|
300
|
+
/** Opens a stored draft in the compose form, the open message by default */
|
|
301
|
+
editDraft(messageId?: string | null): Promise<boolean>;
|
|
223
302
|
submitDraft(messageId: string, options?: SubmitDraftOptions | null): Promise<any>;
|
|
224
303
|
downloadAttachment(attachmentId: string, suggestedFilename?: string): Promise<void>;
|
|
225
304
|
downloadOriginalMessage(messageId: string, subject?: string): Promise<void>;
|