$emails
Updated on Aug 22, 2025 23 minutes to readThe Email Plugin provides methods to compose, send, and manage emails, as well as create, update, connect, and disconnect private accounts, access signatures and templates, and use an API client for mailbox operations.
Methods
| Method | Description |
|---|---|
| apiClient | Creates an API client for mailbox operations. |
| connectAccountInteractive | Opens OAuth authorization for a private account. |
| create | Opens a compose dialog to create and save an email. |
| createAccount | Creates a private account without dialogs. |
| createAccountInteractive | Opens the private account creation wizard. |
| disconnectAccount | Disconnects a private OAuth account without dialogs. |
| getAccounts | Retrieves available email accounts. |
| getDefaultAccount | Returns the default email account if configured. |
| getSignatures | Retrieves stored email signatures. |
| getTemplates | Retrieves stored email templates. |
| isAccountConnected | Returns an account's OAuth connection state. |
| send | Sends an email using the provided configuration. |
| sendTestMessage | Sends a test email without dialogs. |
| updateAccount | Partially updates a private account without dialogs. |
| updateAccountInteractive | Opens the private account editor. |
Methods Details
apiClient()
• Type
(config: EmailApiClientConfig) => EmailApiClient
• Details
Expects an EmailApiClientConfig object.
Returns an EmailApiClient object.
• Example
// Initialize API client for a specific account
const emailApi = E8App.$emails
.apiClient({ accountId: E8App.vars.account })
.setFolder(E8App.vars.folder);
// 'unread' supports only equal condition, values true | false
// Alternative syntax: ['=', 'unread', true | false]
emailApi.where({ unread: E8App.vars.unread });
// 'hasAttachments' supports only true condition
// Alternative syntax: ['=', 'hasAttachments', true]
if (E8App.vars.hasAttachments) {
emailApi.andWhere({ hasAttachments: true });
}
// 'from' supports only equal condition
// Alternative syntax: ['=', 'from', 'your email']
// Multiple senders supported with 'or'
if (E8App.vars.from) {
emailApi.andWhere([
'or',
...E8App.vars.from.split(';').map(email => ({ from: email.trim().replaceAll('"', '') })),
]);
}
// 'dateCreated' supports only >= | <= conditions
// Timestamp is in UTC, filter applies only by date (time ignored)
if (E8App.vars.afterDate) {
emailApi.andWhere(['>=', 'dateCreated', E8App.$timestamp.parse(E8App.vars.afterDate)]);
}
if (E8App.vars.beforeDate) {
emailApi.andWhere(['<=', 'dateCreated', E8App.$timestamp.parse(E8App.vars.beforeDate)]);
}
// 'subject' supports only LIKE condition
if (E8App.vars.subject) {
emailApi.andWhere(['like', 'subject', E8App.vars.subject]);
}
// Recursive function to fetch messages batch by batch
const getBatch = (pageToken) => {
emailApi
.getMessages(pageToken || null)
.then(batch => {
console.log("Messages:", batch.values);
// Continue loading next page if available
if (batch.nextPageToken) {
getBatch(batch.nextPageToken);
}
})
.catch(e => {
console.error("Error fetching messages:", e.message);
});
};
// Start fetching messages
getBatch();
// ----------------------------------------------
// Additional usage examples of EmailApiClient
// ----------------------------------------------
// Initialize another client directly
const client = E8App.$emails.apiClient({
accountId: "12345", // Replace with a real accountId
});
// Example: get list of folders
client.getFolders().then(folders => {
console.log("Folders:", folders);
});
// Example: fetch first page of messages
client.getMessages(null).then(messages => {
console.log("Messages:", messages.values);
});
// Example: get a single message by ID
client.getMessage("abc123").then(message => {
console.log("Message:", message);
});
// Example: get attachments for a message
client.getAttachments("abc123").then(attachments => {
console.log("Attachments:", attachments);
});
// Example: mark a message as read
client.markMessageAsRead("abc123").then(() => {
console.log("Message marked as read");
});
connectAccountInteractive()
• Type
(accountId: string) => Promise<boolean>
• Details
Starts OAuth authorization for the current user's private Gmail or Microsoft 365 account. SMTP accounts do not support this operation.
Call this method directly from a user click handler so the browser can open the authorization tab. The method opens the tab, navigates it to the provider, and shows a cancellable waiting dialog. If automatic opening is blocked, the dialog provides a Connect link. In the mobile application, authorization opens through the external browser integration.
Resolves after the waiting dialog closes with the persisted connection state: true if connected, otherwise false. Cancelling does not reject the Promise. An already connected account resolves with true without starting another authorization. Request failures reject the Promise.
• Example
// Invoke this handler directly from the Connect button.
E8App.$methods.set('connectEmailAccount', async function () {
const connected = await E8App.$emails.connectAccountInteractive(E8App.vars.accountId);
console.log('Connected:', connected);
});
create()
• Type
(config: EmailConfig, scriptAlias: E8ScriptAlias, objectId: E8ObjectId) => Promise<Email>
• Details
Expects an EmailConfig object, a script alias, and an object identifier.
Returns a Promise that resolves with an Email object.
• Example
E8App.$emails.create(
{
accountId: E8App.vars.defaultAccount,
to: 'email@email.com',
subject: 'Business',
body: 'Hello...',
attachments: []
},
'lstInvoices',
1
);
createAccount()
• Type
(data: EmailAccountInput & { label: string; type: 'smtp' | 'gmail' | 'office' }) => Promise<EmailAccount>
• Details
Creates a private account for the current user without opening a dialog. Accepts EmailAccountInput model fields.
Resolves with the persisted EmailAccount object. Creating a Gmail or Microsoft 365 account saves its settings; use connectAccountInteractive() from a subsequent user click to authorize it.
• Example
const account = await E8App.$emails.createAccount({
label: 'Personal SMTP',
type: 'smtp',
from_name: 'Alex',
from_email: 'alex@example.com',
smtp_config: {
host: 'smtp.example.com',
port: 587,
encryption: null,
username: 'alex@example.com',
password: E8App.vars.smtpPassword,
},
});
console.log(account.id, account.name);
createAccountInteractive()
• Type
() => Promise<EmailAccount | null>
• Details
Opens the existing private account creation wizard for the current user.
The Promise remains pending when the user saves and continues editing. After the dialog closes, it resolves with the latest persisted EmailAccount object. If the user closes the wizard before saving an account, it resolves with null. An account saved during OAuth setup is still returned even if the user subsequently closes the wizard without finishing authorization.
• Example
const account = await E8App.$emails.createAccountInteractive();
if (account) {
console.log('Saved account:', account.id);
}
disconnectAccount()
• Type
(accountId: string) => Promise<boolean>
• Details
Disconnects the current user's private Gmail or Microsoft 365 account without a confirmation dialog. SMTP accounts do not support this operation.
Resolves with true when disconnection completes. This value indicates successful execution; it does not mean the account remains connected. Failures reject the Promise.
• Example
await E8App.$emails.disconnectAccount(E8App.vars.accountId);
const connected = await E8App.$emails.isAccountConnected(E8App.vars.accountId);
console.log('Connected:', connected);
getAccounts()
• Type
() => Promise<EmailAccount[]>
• Details
Returns a Promise that resolves with an array of EmailAccount objects.
getDefaultAccount()
• Type
() => Promise<EmailAccount | null>
• Details
Returns a Promise that resolves with an EmailAccount object or null if none is configured.
getSignatures()
• Type
() => Promise<EmailSignature[]>
• Details
Returns a Promise that resolves with an array of EmailSignature objects.
getTemplates()
• Type
() => Promise<EmailTemplate[]>
• Details
Returns a Promise that resolves with an array of EmailTemplate objects.
isAccountConnected()
• Type
(accountId: string) => Promise<boolean>
• Details
Returns the persisted OAuth connection state of an account accessible to the current user. It does not open a dialog or send a message. Missing or inaccessible accounts reject the Promise.
SMTP accounts do not use OAuth and return false. Use sendTestMessage() to test sending through SMTP.
• Example
const connected = await E8App.$emails.isAccountConnected(E8App.vars.accountId);
console.log('Connected:', connected);
send()
• Type
(config: EmailConfig, scriptAlias: E8ScriptAlias, objectId: E8ObjectId) => Promise<Email>
• Details
Expects an EmailConfig object, a script alias, and an object identifier.
Returns a Promise that resolves with an Email object.
sendTestMessage()
• Type
(accountId: string) => Promise<{ success: boolean; message: string }>
• Details
Sends the same test message as the account form to the account's own sender email address. Uses the saved account settings and the same access checks as the form's test-send action, without showing confirmation, progress, or result dialogs.
Resolves with success and a message describing the result. A sending failure reported by the server may resolve with success: false; HTTP, network, and other request failures reject the Promise.
• Example
try {
const result = await E8App.$emails.sendTestMessage(E8App.vars.accountId);
if (result.success) {
console.log('Test sent:', result.message);
} else {
console.error('Test failed:', result.message);
}
} catch (error) {
console.error('Test request failed:', error.message);
}
updateAccount()
• Type
(accountId: string, changes: EmailAccountInput) => Promise<EmailAccount>
• Details
Partially updates the current user's private account without opening a dialog. Accepts EmailAccountInput fields; omitted fields retain their saved values. SMTP configuration fields are merged with the saved configuration, so changing the port does not require resubmitting the host, username, or password.
The accountId argument identifies the account. Resolves with the latest persisted EmailAccount object.
• Example
const account = await E8App.$emails.updateAccount(E8App.vars.accountId, {
label: 'Updated name',
from_name: 'Alex Smith',
smtp_config: {
port: 465,
encryption: 'ssl',
},
});
console.log(account.name, account.from.name);
updateAccountInteractive()
• Type
(accountId: string) => Promise<EmailAccount>
• Details
Opens the existing editor for the current user's private account. Access is checked before opening the editor and again on the server when saving.
Resolves after the editor closes with the latest persisted EmailAccount object, including when closed without saving additional changes. Unsaved edits are not included. Saving without closing does not resolve the Promise.
• Example
const account = await E8App.$emails.updateAccountInteractive(E8App.vars.accountId);
console.log('Saved account:', account.id, account.name);