API docs by Redocly

RustMailerApi (1.5.3)

Download OpenAPI specification:

E-mail: rustmailer.git@gmail.com License: https://rustmailer.com/license

A self-hosted IMAP/SMTP middleware designed for developers

RustMailer is a self-hosted IMAP/SMTP middleware platform designed for developers and businesses seeking a robust, scalable, and secure email solution.

- Provides seamless IMAP synchronization and reliable SMTP sending via blazing-fast REST and gRPC APIs.
- Supports programmable email workflows, customizable filters, and webhook notifications.
- Offers multi-account synchronization, license-based access control, and a built-in web UI for easy management.

Whether you're building SaaS platforms, CRM systems, or customer support tools, RustMailer delivers high performance and full control over your email infrastructure.
https://rustmailer.com/docs

AccessToken

Lists all access tokens in the system.

Requires root privileges.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Lists access tokens for a specific account.

Requires root privileges.

path Parameters
account_id
required
integer <uint64>

The ID of the account whose tokens are to be retrieved.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Deletes a specific access token.

Requires root privileges.

path Parameters
token
required
string

The access token to be deleted

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Updates an existing access token.

Requires root privileges.

path Parameters
token
required
string

The access token to be updated.

Request Body schema: application/json; charset=utf-8
required

The request payload.

accounts
Array of integers <uint64> [ items <uint64 > ]

A set of account information associated with the token.

description
string <= 255 characters

An optional description of the token's purpose or usage.

access_scopes
Array of strings (AccessTokenScope)
Items Enum: "Api" "Metrics"

A set of scopes defining the token's access permissions.

object (AccessControl)

Optional access control settings

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "accounts": [
    ],
  • "description": "string",
  • "access_scopes": [
    ],
  • "acl": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Creates a new access token.

Requires root privileges.

Request Body schema: application/json; charset=utf-8
required

The request payload

accounts
required
Array of integers <uint64> [ items <uint64 > ]

A set of account information associated with the token.

description
string <= 255 characters

An optional description of the token's purpose or usage.

access_scopes
required
Array of strings (AccessTokenScope)
Items Enum: "Api" "Metrics"

A set of scopes defining the token's access permissions.

object (AccessControl)

Optional access control settings

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "accounts": [
    ],
  • "description": "string",
  • "access_scopes": [
    ],
  • "acl": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Regenerates the root access token.

Requires root privileges.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Reset the Root user's password.

Only callable by an already authenticated Root user. This endpoint updates the Root password to password_str and regenerates the root_token, invalidating any previous token.

Request Body schema: text/plain; charset=utf-8
required
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Account

Get account details by account ID

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "imap": {
    },
  • "smtp": {
    },
  • "enabled": true,
  • "mailer_type": "ImapSmtp",
  • "email": "string",
  • "name": "string",
  • "minimal_sync": true,
  • "capabilities": [
    ],
  • "dsn_capable": true,
  • "date_since": {
    },
  • "folder_limit": 0,
  • "sync_folders": [
    ],
  • "full_sync_interval_min": 0,
  • "incremental_sync_interval_sec": 0,
  • "known_folders": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "use_proxy": 0
}

Delete an account by ID - WARNING: This permanently removes the account and all associated resources

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Update an existing account

Request Body schema: application/json; charset=utf-8
required

Account update request payload

enabled
boolean

Represents the account activation status.

If this value is false, all account-related resources will be unavailable and any attempts to access them should return an error indicating the account is inactive.

name
string

Display name for the account (optional)

object (ImapConfig)

IMAP server configuration

object (SmtpConfig)

SMTP server configuration

object (DateSince)

Controls initial synchronization time range

When dealing with large mailboxes, this restricts scanning to:

  • Messages after specified starting point
  • Or within sliding window

Use Cases

  • Event-driven systems (only sync recent actionable emails)
  • First-time sync optimization for large accounts
  • Reducing server load during resyncs
folder_limit
integer <uint32> >= 100

Max emails to sync for this folder. If not set, sync all emails. otherwise sync up to n most recent emails (min 10).

sync_folders
Array of strings

Configuration for selective folder (mailbox/label) synchronization

  • For IMAP/SMTP accounts: Stores the mailbox names, since IMAP mailboxes do not have stable IDs. Synchronization is keyed by the folder name.

  • For Gmail API accounts: A Gmail label is treated as a mailbox (model mapping). Since label names can be easily changed, the stable labelId is recorded here instead of the label name.

Defaults to standard folders (INBOX, Sent) if empty. Modified folders will be automatically synced on the next update.

full_sync_interval_min
integer <int64> [ 10 .. 10080 ]

Full sync interval (minutes)

incremental_sync_interval_sec
integer <int64> [ 10 .. 3600 ]

Incremental sync interval (seconds)

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection to external APIs (e.g., Gmail, Outlook).

  • If None or not provided, the client will connect directly to the API server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID for API requests.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "enabled": true,
  • "name": "string",
  • "imap": {
    },
  • "smtp": {
    },
  • "date_since": {
    },
  • "folder_limit": 100,
  • "sync_folders": [
    ],
  • "full_sync_interval_min": 10,
  • "incremental_sync_interval_sec": 10,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Create a new account

Request Body schema: application/json; charset=utf-8
required

Account creation request payload

email
required
string

Email address associated with this account

This field represents the user's email address and is required for account creation. Once set during account creation, the email address cannot be modified.

name
string

Display name for the account (optional)

object (ImapConfig)

IMAP server configuration

object (SmtpConfig)

SMTP server configuration

enabled
required
boolean

Represents the account activation status.

If this value is false, all account-related resources will be unavailable and any attempts to access them should return an error indicating the account is inactive.

mailer_type
required
string
Enum: "ImapSmtp" "GmailApi"

Method used to access and manage emails.

object (DateSince)

Controls initial synchronization time range

When dealing with large mailboxes, this restricts scanning to:

  • Messages after specified starting point
  • Or within sliding window

Use Cases

  • Event-driven systems (only sync recent actionable emails)
  • First-time sync optimization for large accounts
  • Reducing server load during resyncs
folder_limit
integer <uint32> >= 100

Max emails to sync for this folder. If not set, sync all emails. otherwise sync up to n most recent emails (min 10).

minimal_sync
boolean

Minimal sync mode flag

When enabled (true), only the most essential metadata will be synchronized: Recommended for:

  • Extremely resource-constrained environments
  • Accounts where only new message notification is needed
full_sync_interval_min
integer <int64> [ 10 .. 10080 ]

Full sync interval (minutes), default 30m

incremental_sync_interval_sec
required
integer <int64> [ 10 .. 3600 ]

Incremental sync interval (seconds), default 60s

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection to external APIs (e.g., Gmail, Outlook).

  • If None or not provided, the client will connect directly to the API server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID for API requests.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "email": "string",
  • "name": "string",
  • "imap": {
    },
  • "smtp": {
    },
  • "enabled": true,
  • "mailer_type": "ImapSmtp",
  • "date_since": {
    },
  • "folder_limit": 100,
  • "minimal_sync": true,
  • "full_sync_interval_min": 10,
  • "incremental_sync_interval_sec": 10,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "imap": {
    },
  • "smtp": {
    },
  • "enabled": true,
  • "mailer_type": "ImapSmtp",
  • "email": "string",
  • "name": "string",
  • "minimal_sync": true,
  • "capabilities": [
    ],
  • "dsn_capable": true,
  • "date_since": {
    },
  • "folder_limit": 0,
  • "sync_folders": [
    ],
  • "full_sync_interval_min": 0,
  • "incremental_sync_interval_sec": 0,
  • "known_folders": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "use_proxy": 0
}

List accounts with optional pagination parameters

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Get the running state of an account

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "account_id": 0,
  • "last_full_sync_start": 0,
  • "last_full_sync_end": 0,
  • "last_incremental_sync_start": 0,
  • "last_incremental_sync_end": 0,
  • "errors": [
    ],
  • "is_initial_sync_completed": true,
  • "initial_sync_folders": [
    ],
  • "current_syncing_folder": "string",
  • "current_batch_number": 0,
  • "current_total_batches": 0,
  • "initial_sync_start_time": 0,
  • "initial_sync_end_time": 0
}

Get a minimal list of active accounts for use in selectors when creating account-related resources

This endpoint provides a lightweight list of accounts containing only essential information (id and name). It's primarily designed for UI selectors/dropdowns when creating or associating resources with accounts.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

AutoConfig

Retrieve mail server configuration for a given email address

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "imap": {
    },
  • "smtp": {
    },
  • "oauth2": {
    }
}

Hook

Retrieve an event hook configuration

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "account_id": 0,
  • "email": "string",
  • "description": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "global": 0,
  • "enabled": true,
  • "hook_type": "Http",
  • "http": {
    },
  • "nats": {
    },
  • "vrl_script": "string",
  • "call_count": 0,
  • "success_count": 0,
  • "failure_count": 0,
  • "last_error": "string",
  • "watched_events": [
    ],
  • "use_proxy": 0
}

Delete an event hook configuration

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Update an event hook

Request Body schema: application/json; charset=utf-8
required

Request Body

description
string

Optional description providing additional context about the hook.

enabled
boolean

Indicates whether the hook is active and processing events upon creation.

object (HttpConfig)

Optional HTTP configuration for HTTP-based hook.

object (NatsConfig)

Optional NATS configuration for NATS-based hook.

vrl_script
string

Optional VRL (Vector Remap Language) script for customizing the hook payload.

watched_events
Array of strings (EventType)
Items Enum: "EmailAddedToFolder" "EmailFlagsChanged" "EmailSentSuccess" "EmailSendingError" "UIDValidityChange" "MailboxDeletion" "MailboxCreation" "AccountFirstSyncCompleted" "EmailBounce" "EmailFeedBackReport" "EmailOpened" "EmailLinkClicked"

List of event types the hook is configured to monitor.

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection.

  • If None or not provided, the client will connect directly to the webhook server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "enabled": true,
  • "http": {
    },
  • "nats": {
    },
  • "vrl_script": "string",
  • "watched_events": [
    ],
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Create a new event hook

Request Body schema: application/json; charset=utf-8
required

Request Body

account_id
integer <uint64>

Unique identifier of the account associated with the hook.

description
string

Optional description providing additional context about the hook.

enabled
required
boolean

Indicates whether the hook is active and processing events upon creation.

hook_type
required
string
Enum: "Http" "Nats"

The type of hook (e.g., HTTP or NATS).

object (HttpConfig)

Optional HTTP configuration for HTTP-based hook.

object (NatsConfig)

Optional NATS configuration for NATS-based hook.

vrl_script
string

Optional VRL (Vector Remap Language) script for customizing the hook payload.

watched_events
required
Array of strings (EventType)
Items Enum: "EmailAddedToFolder" "EmailFlagsChanged" "EmailSentSuccess" "EmailSendingError" "UIDValidityChange" "MailboxDeletion" "MailboxCreation" "AccountFirstSyncCompleted" "EmailBounce" "EmailFeedBackReport" "EmailOpened" "EmailLinkClicked"

List of event types the hook is configured to monitor.

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection.

  • If None or not provided, the client will connect directly to the webhook server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "account_id": 0,
  • "description": "string",
  • "enabled": true,
  • "hook_type": "Http",
  • "http": {
    },
  • "nats": {
    },
  • "vrl_script": "string",
  • "watched_events": [
    ],
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "account_id": 0,
  • "email": "string",
  • "description": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "global": 0,
  • "enabled": true,
  • "hook_type": "Http",
  • "http": {
    },
  • "nats": {
    },
  • "vrl_script": "string",
  • "call_count": 0,
  • "success_count": 0,
  • "failure_count": 0,
  • "last_error": "string",
  • "watched_events": [
    ],
  • "use_proxy": 0
}

List event hooks (root)

Requires root privileges.

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Get event examples

Responses

Response samples

Content type
application/json; charset=utf-8
null

Test and debug VRL transformation scripts

Request Body schema: application/json; charset=utf-8
required

JSON body containing the script and input context.

program
required
string

The VRL script program to be tested.

event
string

Optional event data to be used as input for testing the VRL script.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "program": "string",
  • "event": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "result": null,
  • "error": "string"
}

List hook tasks

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

status
string (TaskStatus)
Enum: "Scheduled" "Running" "Success" "Failed" "Removed" "Stopped"

Filter by task status (optional)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Get hook task details

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "created_at": 0,
  • "status": "Scheduled",
  • "stopped_reason": "string",
  • "error": "string",
  • "last_duration_ms": 0,
  • "retry_count": 0,
  • "scheduled_at": 0,
  • "account_id": 0,
  • "account_email": "string",
  • "event": null,
  • "event_type": "EmailAddedToFolder"
}

Mark a hook task for deletion from queue

Initiates asynchronous removal of an event hook task by marking it for deletion. The task will be:

  1. Immediately marked as "cancelled" in the system
  2. Prevented from any further execution attempts
  3. Physically removed by background cleanup processes

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

License

Retrieve current license information

Requires root privileges.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "string",
  • "issued_license_id": "string",
  • "application_name": "string",
  • "customer_name": "string",
  • "created_at": 0,
  • "license_type": "Trial",
  • "expires_at": 0,
  • "last_expires_at": 0,
  • "license_content": "string",
  • "max_accounts": 0
}

Upload and activate a new license

Requires root privileges.

Request Body schema: text/plain; charset=utf-8
required

Raw license key string (text/plain content-type)

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "string",
  • "issued_license_id": "string",
  • "application_name": "string",
  • "customer_name": "string",
  • "created_at": 0,
  • "license_type": "Trial",
  • "expires_at": 0,
  • "last_expires_at": 0,
  • "license_content": "string",
  • "max_accounts": 0
}

Mailbox

Returns all available mailboxes for the given account.

  • For IMAP/SMTP accounts, this corresponds to folders/mailboxes.
  • For Gmail API accounts, this corresponds to labels visible via the list messages API (serving as mailbox equivalents).

Both account types support two modes:

  • Using the local cache of mailboxes/labels.
  • Querying the remote service directly for the latest state.
query Parameters
remote
boolean

If true, includes remote mailboxes from the server.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Returns a list of mailboxes that the user is currently subscribed to.

This is only applicable to IMAP/SMTP accounts.

In the IMAP protocol, this list reflects which mailboxes the user has chosen to subscribe to on the server side, as maintained by the IMAP server. This is not a synchronized list of all mail folders, but rather the server-side subscription list.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Subscribes to a mailbox with the specified name.

This operation is only applicable to IMAP/SMTP accounts.

In the IMAP protocol, it marks the mailbox as subscribed on the server side. It does not create or synchronize the mailbox, but only updates the server-maintained subscription list.

Unsupported for Gmail API accounts.

Request Body schema: text/plain; charset=utf-8
required

The name of the mailbox to subscribe to.

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Unsubscribes from a mailbox with the specified name.

This operation is only applicable to IMAP/SMTP accounts.

In the IMAP protocol, it removes the mailbox from the subscription list on the server side. It does not delete the mailbox or stop synchronization, but only affects the server’s record of subscribed folders.

Unsupported for Gmail API accounts.

Request Body schema: text/plain; charset=utf-8
required

The name of the mailbox to unsubscribe from.

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Creates a new mailbox for a given account.

Request Body schema: application/json; charset=utf-8
required

The name of the mailbox to create.

mailbox_name
required
string

Name of the mailbox or label.

  • For IMAP accounts, this is the name of the mailbox to create. Supports hierarchical paths using / as a separator. For example, "a/b" creates mailbox b under parent mailbox a. Note: The parent mailbox (a) must already exist.
  • For Gmail API accounts, this corresponds to the label's name. Gmail labels do not require the parent to exist beforehand; nested labels are created automatically.
object (LabelColor)

Optional color settings for the label (Gmail API only).

Only applicable to Gmail API accounts. See [LabelColor] for the allowed text_color and background_color values.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox_name": "string",
  • "label_color": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Deletes an existing mailbox from the specified account.

Request Body schema: text/plain; charset=utf-8
required

The name of the mailbox to delete.

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Renames an existing mailbox under the specified account.

Request Body schema: application/json; charset=utf-8
required

The rename payload including old and new mailbox names.

current_name
required
string [ 1 .. 1024 ] characters

Current name of the mailbox or label.

  • For IMAP accounts, this is the existing mailbox name.
  • For Gmail API accounts, this is the existing label name.
new_name
string [ 1 .. 1024 ] characters

New name for the mailbox or label (optional).

object (LabelColor)

Optional color settings for the label (Gmail API only).

Only applicable to Gmail API accounts. See [LabelColor] for allowed text_color and background_color values.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "current_name": "string",
  • "new_name": "string",
  • "label_color": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Message

Moves messages from one mailbox to another for the specified account.

Request Body schema: application/json; charset=utf-8
required

specifying the source and destination mailboxes and messages

ids
required
Array of strings

A list of unique message identifiers as strings.

  • For IMAP accounts, each UID is converted to a numeric string (parseable back to u32).
  • For Gmail API accounts, each element is a message ID (mid) returned by the API. Unifying them as strings simplifies handling across different backends.
current_mailbox
required
string

The name of the mailbox from which the messages will be moved. For IMAP: the decoded, human-readable name of the mailbox (e.g., "INBOX"). For Gmail API: represents the label name.

target_mailbox
required
string

The name of the mailbox to which the messages will be moved. For IMAP: the decoded, human-readable name of the mailbox (e.g., "INBOX"). For Gmail API: represents the label name.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "ids": [
    ],
  • "current_mailbox": "string",
  • "target_mailbox": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Copies messages from one mailbox to another for the specified account.

Request Body schema: application/json; charset=utf-8
required

specifying the source and destination mailboxes and messages.

ids
required
Array of strings

A list of unique message identifiers as strings.

  • For IMAP accounts, each UID is converted to a numeric string (parseable back to u32).
  • For Gmail API accounts, each element is a message ID (mid) returned by the API. Unifying them as strings simplifies handling across different backends.
current_mailbox
required
string

The name of the mailbox from which the messages will be moved. For IMAP: the decoded, human-readable name of the mailbox (e.g., "INBOX"). For Gmail API: represents the label name.

target_mailbox
required
string

The name of the mailbox to which the messages will be moved. For IMAP: the decoded, human-readable name of the mailbox (e.g., "INBOX"). For Gmail API: represents the label name.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "ids": [
    ],
  • "current_mailbox": "string",
  • "target_mailbox": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Deletes messages from a mailbox or moves them to the trash for the specified account.

Request Body schema: application/json; charset=utf-8
required

specifying the mailbox and messages to delete.

ids
required
Array of strings

A list of unique message identifiers as strings.

  • For IMAP accounts, each UID is converted to a numeric string (parseable back to u32).
  • For Gmail API accounts, each element is a message ID (mid) returned by the API. Unifying them as strings simplifies handling across different backends.
mailbox
string

The decoded, human-readable name of the mailbox containing the email (e.g., "INBOX"). (IMAP only) This name is presented as it appears to users, with any encoding (e.g., UTF-7) automatically handled by the system, so no manual decoding is required. In Gmail API, this field is not required and can be set to None.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "ids": [
    ],
  • "mailbox": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Updates flags on messages in a mailbox for the specified account.

Request Body schema: application/json; charset=utf-8
required

specifying the mailbox, messages, and flags to modify.

uids
required
Array of integers <uint32> [ items <uint32 > ]

A list of unique identifiers (UIDs) of the messages to be flagged or unflagged.

mailbox
required
string

The name of the mailbox where the messages are located. The decoded, human-readable name of the mailbox containing the email (e.g., "INBOX"). This name is presented as it appears to users, with any encoding (e.g., UTF-7) automatically handled by the system, so no manual decoding is required.

required
object (FlagAction)

The action to be performed on the message flags.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "uids": [
    ],
  • "mailbox": "string",
  • "action": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Lists messages in a specified mailbox for the given account.

query Parameters
mailbox
required
string

The decoded, human-readable name of the mailbox containing the email (e.g., "INBOX"). This name is presented as it appears to users, with any encoding (e.g., UTF-7) automatically handled by the system, so no manual decoding is required.

remote
boolean

fetches messages from the IMAP server; otherwise, uses local data.

next_page_token
string

The token for fetching the next page of results in pagination.

  • If None, this indicates that the first page should be returned.
  • If Some(token), the page corresponding to this token will be fetched.
page_size
required
integer <uint64>

The number of messages per page.

desc
boolean

lists messages in descending order; otherwise, ascending. internal date

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "next_page_token": "string",
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Lists threads in a specified mailbox for the given account.

query Parameters
mailbox
required
string

The decoded, human-readable name of the mailbox containing the email (e.g., "INBOX"). This name is presented as it appears to users, with any encoding (e.g., UTF-7) automatically handled by the system, so no manual decoding is required.

page
required
integer <uint64>

The page number for pagination (1-based).

page_size
required
integer <uint64>

The number of messages per page.

desc
boolean

lists messages in descending order; otherwise, ascending. internal date

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Get thread's envelopes in a specified mailbox for the given account.

query Parameters
thread_id
required
integer <uint64>

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Fetches the content of a specific email for the given account.

Request Body schema: application/json; charset=utf-8
required

specifying the mailbox and message to fetch.

mailbox
string

The name of the mailbox containing the message

  • Required for IMAP/SMTP accounts
  • Not used for Gmail API
id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
max_length
integer <uint64>

Optional maximum length to retrieve for text parts (useful for large messages)

  • Supported by both IMAP/SMTP and Gmail API
Array of objects (EmailBodyPart)

Specific email body parts to retrieve (e.g., TEXT, HTML)

  • Only used for IMAP/SMTP accounts
  • Comes from list_messages results
Array of objects (ImapAttachment)

Optional list of attachments to include inline in the response

  • Only used for IMAP/SMTP accounts
  • Comes from list_messages results

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox": "string",
  • "id": "string",
  • "max_length": 0,
  • "sections": [
    ],
  • "inline": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "plain": {
    },
  • "html": "string",
  • "attachments": [
    ]
}

Fetches an attachment from a specific email for the given account.

Request Body schema: application/json; charset=utf-8
required

specifying the mailbox, message, and attachment to fetch.

mailbox
string

IMAP only: The name of the mailbox where the message is located. Not used for Gmail API accounts.

object (ImapAttachment)

IMAP only: The metadata describing the attachment to fetch. Not used for Gmail API accounts.

id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
object (AttachmentInfo)

Gmail API only: attachment info used to fetch it via Gmail API. Not used for IMAP accounts.

filename
string

Optional: The original filename of the attachment, if available.

  • Gmail API only.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox": "string",
  • "attachment": {
    },
  • "id": "string",
  • "attachment_info": {
    },
  • "filename": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Fetches the full content of a specific email for the given account.

query Parameters
mailbox
string

The decoded, human-readable name of the mailbox containing the email (e.g., "INBOX"). This name is presented as it appears to users, with any encoding (e.g., UTF-7) automatically handled by the system, so no manual decoding is required.

id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
filename
string

An optional filename for the attachment (defaults to a timestamped .elm file).

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Searches for messages in mailboxes for the specified account. performs the search on the IMAP server;

query Parameters
next_page_token
string

The token for fetching the next page of results in pagination.

  • If None, this indicates that the first page should be returned.
  • If Some(token), the page corresponding to this token will be fetched.
page_size
required
integer <uint64>

The number of messages per page.

desc
boolean

If true, lists results in descending order; otherwise, ascending. imap account only

Request Body schema: application/json; charset=utf-8
required

specifying the search criteria (e.g., keywords, flags).

required
object

The search criteria to apply (can be a simple condition or complex logical expression)

mailbox
string

The name of the mailbox to search in

  • For IMAP accounts, this field is required and specifies which mailbox (e.g. INBOX, Sent, or a custom folder) the search will run against.
  • For Gmail API accounts, this field is optional. If provided, it is treated as a label name and will override any label filter specified in the query string.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "search": {
    },
  • "mailbox": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "next_page_token": "string",
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Creates a reply draft email for the specified account. The server internally constructs the reply email, automatically linking it to the original email thread by applying appropriate headers such as `References` and `In-Reply-To`.

The newly created draft is appended into the specified draft mailbox.

Request Body schema: application/json; charset=utf-8
required

Request body containing original message location and reply content.

mailbox_name
required
string

The name of the mailbox or label containing the original message.

  • For IMAP accounts, this is the mailbox name where the source message resides.
  • For Gmail API accounts, this refers to the label name associated with the source message. This is used to locate the message being replied to.
id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
preview
string [ 1 .. 200 ] characters

A preview text for the reply email.

This optional field provides a short summary or preview of the reply content.

text
string [ 1 .. 10000 ] characters

The plain text body of the reply email.

This field is optional and can be used to provide plain text content.

html
string [ 1 .. 50000 ] characters

The HTML body of the reply email.

This field is optional and can be used to provide HTML content.

draft_folder_path
string

The path of the folder used to store drafts (IMAP accounts only).

For example: "[Gmail]/Drafts". This can be obtained from the name field of the mailbox via the list-mailboxes endpoint. For Gmail API accounts, this field is ignored.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox_name": "string",
  • "id": "string",
  • "preview": "string",
  • "text": "string",
  • "html": "string",
  • "draft_folder_path": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Mta

Retrieves the MTA (Mail Transfer Agent) configuration by its unique name.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "description": "string",
  • "credentials": {
    },
  • "server": {
    },
  • "created_at": 0,
  • "dsn_capable": true,
  • "updated_at": 0,
  • "last_access_at": 0,
  • "use_proxy": 0
}

Deletes an existing MTA configuration identified by its name.

Requires root privileges.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Updates an existing MTA configuration by its name.

Requires root privileges.

Request Body schema: application/json; charset=utf-8
required

The MTA update request payload.

description
string

Optional descriptive text about the MTA.

object (MTACredentials)

Optional updated credentials.

object (SmtpServerConfig)

Optional updated SMTP server configuration.

dsn_capable
boolean

Optional updated DSN support flag.

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection.

  • If None or not provided, the client will connect directly to the MTA server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "credentials": {
    },
  • "server": {
    },
  • "dsn_capable": true,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Creates a new MTA configuration.

Requires root privileges.

Request Body schema: application/json; charset=utf-8
required

The MTA creation request payload.

description
string

Optional descriptive text about the MTA.

required
object (MTACredentials)

Credentials used for authenticating with the MTA server.

required
object (SmtpServerConfig)

SMTP server configuration details.

dsn_capable
required
boolean

Whether the MTA supports DSN (Delivery Status Notification).

use_proxy
integer <uint64>

Optional proxy ID for establishing the connection.

  • If None or not provided, the client will connect directly to the MTA server.
  • If Some(proxy_id), the client will use the pre-configured proxy with the given ID.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "credentials": {
    },
  • "server": {
    },
  • "dsn_capable": true,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Retrieves a list of all MTA

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Sends a test email using the specified Mail Transfer Agent (MTA).

Request Body schema: application/json; charset=utf-8
required

request payload.

from
required
string

The email address of the sender (e.g., "no-reply@yourdomain.com").

to
required
string

The email address of a single recipient (e.g., "user@example.com").

subject
required
string [ 1 .. 256 ] characters

The subject line of the email.

message
required
string [ 1 .. 1024 ] characters

The plain text body content of the email, sent as the text/plain part of the email.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "from": "string",
  • "to": "string",
  • "subject": "string",
  • "message": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

OAuth2

Retrieves the OAuth2 configuration for a specified name.

Requires root privileges. This endpoint fetches the OAuth2 configuration identified by the given name.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "description": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "auth_url": "string",
  • "token_url": "string",
  • "redirect_uri": "string",
  • "scopes": [
    ],
  • "extra_params": {
    },
  • "enabled": true,
  • "use_proxy": 0,
  • "created_at": 0,
  • "updated_at": 0
}

Deletes an OAuth2 configuration by name.

Requires root privileges. This endpoint removes the OAuth2 configuration identified by the specified name.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Updates an existing OAuth2 configuration.

Requires root privileges. This endpoint updates the OAuth2 configuration identified by the specified name

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the updated configuration details

description
string

A description of what this configuration is used for.

client_id
string

The client ID used for authenticating the application with the OAuth2 provider.

client_secret
string

The client secret used in conjunction with the client ID.

auth_url
string

The URL to redirect users to for OAuth2 authorization.

token_url
string

The URL to exchange authorization codes for access tokens.

redirect_uri
string

The URI where the OAuth2 provider will redirect to after authorization.

scopes
Array of strings

The scopes of access that are being requested (e.g., email, profile).

object

Any additional parameters to include in the OAuth2 requests (e.g., access_type, prompt).

enabled
boolean

Indicates whether this configuration is enabled or disabled.

use_proxy
integer <uint64>

route OAuth through proxy (when direct access is blocked)

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "auth_url": "string",
  • "token_url": "string",
  • "redirect_uri": "string",
  • "scopes": [
    ],
  • "extra_params": {
    },
  • "enabled": true,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Creates a new OAuth2 configuration.

Requires root privileges. This endpoint creates a new OAuth2 configuration based on the provided request data.

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the details for the new OAuth2 configuration

description
string

A description of what this configuration is used for.

client_id
required
string

The client ID used for authenticating the application with the OAuth2 provider.

client_secret
required
string

The client secret used in conjunction with the client ID.

auth_url
required
string

The URL to redirect users to for OAuth2 authorization.

token_url
required
string

The URL to exchange authorization codes for access tokens.

redirect_uri
required
string

The URI where the OAuth2 provider will redirect to after authorization.

scopes
Array of strings

The scopes of access that are being requested (e.g., email, profile).

object

Any additional parameters to include in the OAuth2 requests (e.g., access_type, prompt).

enabled
required
boolean

Indicates whether this configuration is enabled or disabled.

use_proxy
integer <uint64>

route OAuth through proxy (when direct access is blocked)

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "auth_url": "string",
  • "token_url": "string",
  • "redirect_uri": "string",
  • "scopes": [
    ],
  • "extra_params": {
    },
  • "enabled": true,
  • "use_proxy": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Lists OAuth2 configurations with pagination and sorting options.

This endpoint retrieves a paginated list of OAuth2 configurations, allowing for optional pagination and sorting parameters. It requires root access.

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Generates an OAuth2 authorization URL for a specific account.

This endpoint creates an authorization URL for the specified OAuth2 configuration and account ID. It requires root access and returns the URL as plain text.

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the OAuth2 configuration name and account ID.

account_id
required
integer <uint64>

The ID of the account for which the authorization URL is generated.

oauth2_id
required
integer <uint64>

The name of the OAuth2 configuration to use for generating the authorization URL.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "account_id": 0,
  • "oauth2_id": 0
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Retrieves OAuth2 access tokens for a specified account.

This endpoint fetches the OAuth2 access tokens associated with the given account ID.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "account_id": 0,
  • "oauth2_id": 0,
  • "access_token": "string",
  • "refresh_token": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Configures an external OAuth2 token for a specified account.

This endpoint allows two usage modes:

  1. If only an access_token is provided, RustMailer will store it directly.
  • In this mode, RustMailer cannot refresh the token, since it has no associated OAuth2 configuration or refresh token.
  • The caller is responsible for periodically updating the access token by calling this endpoint again.
  1. If both oauth2_id and refresh_token are provided, it means the external OAuth2 authorization flow has been completed outside RustMailer.
  • Since the OAuth2 configuration (including client_id and client_secret) is already stored in RustMailer, the service can use the refresh token to obtain new access tokens automatically.

Note: The oauth2_id must reference a valid OAuth2 configuration already created in RustMailer.

Request Body schema: application/json; charset=utf-8
required
oauth2_id
integer <uint64>

The id of the OAuth2 configuration associated with this access token.

access_token
string

The OAuth2 access token used to authenticate requests to the provider.

refresh_token
string

The OAuth2 refresh token used to obtain new access tokens.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "oauth2_id": 0,
  • "access_token": "string",
  • "refresh_token": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

SendMail

Sends a new email for a specified account.

This endpoint constructs and sends a new email based on the provided request data.

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the details of the email to be sent

object (EmailAddress)

The sender's email address.

If not provided, a default sender address may be used based on the account configuration.

required
Array of objects (Recipient)

The list of recipients for the email.

This field is required and must contain at least one recipient. Each recipient in the list will be handled as a separate send task (e.g., To, Cc, or Bcc).

subject
string

The subject line of the email.

This field is optional and may be omitted for emails without a subject.

text
string

The plain text body of the email.

This field is optional and can be used for emails that support plain text content.

html
string

The HTML body of the email.

This field is optional and can be used for emails that support HTML content.

preview
string

A preview text for the email.

This optional field provides a short summary or preview of the email content, often displayed in email clients.

eml
string

The raw EML content of the email.

This optional field allows specifying the email content in EML format, overriding other content fields if provided.

template_id
integer <uint64>

The name of a template to use for rendering the email.

This optional field specifies a predefined email template to generate the email content.

Array of objects (MailAttachment)

A list of attachments to include in the email.

This optional field allows adding file attachments to the email.

object

Custom email headers to include in the email.

This optional field allows specifying additional headers (e.g., Reply-To, X-Custom-Header) as key-value pairs.

object (SendControl)

Configuration options for controlling the email sending process.

This required field specifies settings such as scheduling, or retry policies for sending the email.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "from": {
    },
  • "recipients": [
    ],
  • "subject": "string",
  • "text": "string",
  • "html": "string",
  • "preview": "string",
  • "eml": "string",
  • "template_id": 0,
  • "attachments": [
    ],
  • "headers": {
    },
  • "send_control": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Sends a reply to an existing email for a specified account.

This endpoint constructs and sends a reply to an email based on the provided request data.

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the details of the email reply

mailbox_name
required
string

The name of the mailbox containing the original message.

This is used to locate the source message that is being replied to.

id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
text
string

The plain text body of the reply email.

This field is optional and can be used to provide plain text content.

html
string

The HTML body of the reply email.

This field is optional and can be used to provide HTML content.

preview
string

A preview text for the reply email.

This optional field provides a short summary or preview of the reply content.

object

Custom email headers to include in the reply email.

This optional field allows specifying additional headers as key-value pairs.

reply_all
required
boolean

Whether to reply to all original recipients (Reply-All).

If true, the reply will be sent to all original recipients, including Cc.

Array of objects (MailAttachment)

A list of attachments to include in the reply.

This optional field allows adding new file attachments to the reply email.

Array of objects (EmailAddress)

A list of Cc recipients to include in the reply.

This optional field allows explicitly specifying Cc recipients.

Array of objects (EmailAddress)

A list of Bcc recipients to include in the reply.

This optional field allows explicitly specifying Bcc recipients.

include_original
required
boolean

Whether to include the original message in the reply body.

If true, the original message content will be quoted and included in the reply.

include_all_attachments
required
boolean

Whether to include all original attachments in the reply.

If true, all attachments from the original message will be included in the reply.

timezone
string

The sender's timezone (e.g., "Asia/Shanghai").

This optional field may be used for formatting date/time in the reply body.

object (SendControl)

Configuration options for controlling the email sending process.

This required field specifies settings such as scheduling, or retry policies for sending the reply.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox_name": "string",
  • "id": "string",
  • "text": "string",
  • "html": "string",
  • "preview": "string",
  • "headers": {
    },
  • "reply_all": true,
  • "attachments": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "include_original": true,
  • "include_all_attachments": true,
  • "timezone": "string",
  • "send_control": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Forwards an existing email for a specified account.

This endpoint constructs and sends a forwarded email based on the provided request data.

Request Body schema: application/json; charset=utf-8
required

A JSON payload containing the details of the email to be forwarded.

mailbox_name
required
string

The name of the mailbox containing the original message.

This is used to locate the source message that is being forwarded.

id
required
string

The unique ID of the message, either IMAP UID or Gmail API MID.

  • For IMAP accounts, this is the UID converted to a string. It must be a valid numeric string that can be parsed back to a u32.
  • For Gmail API accounts, this is the message ID (mid) returned by the API.
required
Array of objects (EmailAddress)

The list of primary recipients to forward the email to.

At least one recipient must be specified.

Array of objects (EmailAddress)

A list of Cc recipients to include in the forwarded email.

This optional field allows explicitly specifying Cc recipients.

Array of objects (EmailAddress)

A list of Bcc recipients to include in the forwarded email.

This optional field allows explicitly specifying Bcc recipients.

text
string

The plain text body of the forwarded email.

This field is optional and can be used to provide additional comments or content.

html
string

The HTML body of the forwarded email.

This field is optional and can be used to provide HTML-formatted content.

preview
string

A preview text for the forwarded email.

This optional field provides a short summary or preview of the email content.

object

Custom email headers to include in the forwarded email.

This optional field allows specifying additional headers as key-value pairs.

timezone
string

The sender's timezone (e.g., "Asia/Shanghai").

This optional field may be used for formatting date/time in the forwarded content.

Array of objects (MailAttachment)

A list of new attachments to include in the forwarded email.

This optional field allows adding additional attachments beyond the original ones.

include_original
required
boolean

Whether to include the original message in the forwarded email body.

If true, the full original message content will be included in the body.

include_all_attachments
required
boolean

Whether to include all original attachments in the forwarded email.

If true, all attachments from the original message will be forwarded as well.

object (SendControl)

Configuration options for controlling the email sending process.

This required field specifies settings such as scheduling or retry policies for sending the forwarded email.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mailbox_name": "string",
  • "id": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "text": "string",
  • "html": "string",
  • "preview": "string",
  • "headers": {
    },
  • "timezone": "string",
  • "attachments": [
    ],
  • "include_original": true,
  • "include_all_attachments": true,
  • "send_control": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Lists email tasks with pagination, sorting, and optional status filtering.

This endpoint retrieves a paginated list of email tasks, filtered by accessible accounts and optionally by task status. It supports sorting in ascending or descending order by creation time.

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

status
string (TaskStatus)
Enum: "Scheduled" "Running" "Success" "Failed" "Removed" "Stopped"

Represents the status of a task in the system.

This enum defines the lifecycle states that a task can be in, from initial scheduling to completion or removal.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Retrieves a specific email task by its ID.

This endpoint fetches the details of an email task identified by the provided ID.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "created_at": 0,
  • "status": "Scheduled",
  • "stopped_reason": "string",
  • "error": "string",
  • "last_duration_ms": 0,
  • "retry_count": 0,
  • "scheduled_at": 0,
  • "account_id": 0,
  • "account_email": "string",
  • "subject": "string",
  • "message_id": "string",
  • "from": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "attachment_count": 0,
  • "cache_key": "string",
  • "envelope": {
    },
  • "save_to_sent": true,
  • "sent_folder": "string",
  • "send_at": 0,
  • "mta": 0,
  • "dsn": {
    },
  • "reply": true,
  • "mailbox": "string",
  • "uid": 0
}

Mark a email task for deletion from queue

Initiates asynchronous removal of an email task by marking it for deletion. The task will be:

  1. Immediately marked as "cancelled" in the system
  2. Prevented from any further execution attempts
  3. Physically removed by background cleanup processes

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

System

Retrieves important system notifications for the RustMail service.

This endpoint returns a consolidated view of all critical system notifications including:

  • Available version updates
  • License expiration warnings

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "release": {
    },
  • "license": {
    }
}

Retrieves an overview of RustMail service metrics.

This endpoint returns a consolidated view of all key metrics including:

  • IMAP traffic (sent and received)
  • Email sent counts (success and failure)
  • Email sent bytes
  • New email arrivals
  • Mail flag changes
  • Email opens
  • Email clicks
  • Event dispatch counts (success and failure for HTTP and NATS)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "pending_email_task_num": 0,
  • "pending_hook_task_num": 0,
  • "account_num": 0,
  • "uptime": 0,
  • "rustmailer_version": "string",
  • "time_series": {
    }
}

Get the full list of SOCKS5 proxy configurations.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Delete a specific proxy configuration by ID. Requires root permission.

path Parameters
id
required
integer <uint64>

The name of the OAuth2 configuration to retrieve

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Retrieve a specific proxy configuration by ID

path Parameters
id
required
integer <uint64>

The name of the OAuth2 configuration to retrieve

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "url": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Update the URL of a specific proxy by ID. Requires root permission.

path Parameters
id
required
integer <uint64>
Request Body schema: text/plain; charset=utf-8
required
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Create a new proxy configuration. Requires root permission.

Request Body schema: text/plain; charset=utf-8
required
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Template

Retrieves an email template by its name.

Returns the template if found, or a ResourceNotFound error if no template matches the provided name.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "description": "string",
  • "account": {
    },
  • "subject": "string",
  • "preview": "string",
  • "format": "Markdown",
  • "text": "string",
  • "html": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "last_access_at": 0
}

Deletes an email template by its name.

Removes the specified template if it exists and the client has access. Returns a ResourceNotFound error if the template is not found.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Updates an existing email template by its name.

Modifies the specified template with the provided update data if it exists and the client has access. Returns a ResourceNotFound error if the template is not found.

Request Body schema: application/json; charset=utf-8
required

JSON payload containing the updated template data.

description
string <= 1024 characters

A brief description of the email template (optional). Maximum length is 1024 characters.

subject
string <= 20480 characters

The subject line of the email (optional). Maximum length is 20,480 characters.

preview
string <= 256 characters

Preview text for the email (optional), displayed in email clients. Maximum length is 256 characters.

text
string <= 8388608 characters

The plain text content of the email template (optional). Maximum length is 8,388,608 characters (approximately 8MB).

html
string <= 8388608 characters

The HTML content of the email template (optional). Maximum length is 8,388,608 characters (approximately 8MB).

format
string
Enum: "Markdown" "Html"

Format of the HTML email content, either Markdown or HTML. Defaults to HTML if not specified.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "subject": "string",
  • "preview": "string",
  • "text": "string",
  • "html": "string",
  • "format": "Markdown"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Creates a new email template.

Saves a new email template based on the provided request data.

Request Body schema: application/json; charset=utf-8
required

JSON payload containing the data needed to create a new email template

description
string <= 1024 characters

A brief description of the email template (optional). Maximum length is 1024 characters.

account_id
integer <uint64>

The associated account information that created or uses this template (optional). None indicates a public template.

subject
required
string <= 20480 characters

The subject line of the email. Maximum length is 20,480 characters.

preview
string <= 256 characters

Preview text for the email (optional), displayed in email clients. Maximum length is 256 characters.

text
string <= 8388608 characters

The plain text content of the email template (optional). Maximum length is 8,388,608 characters (approximately 8MB).

html
string <= 8388608 characters

The HTML content of the email template (optional). Maximum length is 8,388,608 characters (approximately 8MB).

format
string
Enum: "Markdown" "Html"

Format of the HTML email content, either Markdown or HTML. Defaults to HTML if not specified.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "description": "string",
  • "account_id": 0,
  • "subject": "string",
  • "preview": "string",
  • "text": "string",
  • "html": "string",
  • "format": "Markdown"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Lists all email templates with pagination.

Retrieves a paginated list of all email templates. Requires root privileges.

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Lists email templates associated with a specific account.

Retrieves a paginated list of templates for the specified account ID. Requires access to the specified account.

query Parameters
page
integer <uint64>

Optional. The page number to retrieve (starting from 1).

page_size
integer <uint64>

Optional. The number of items per page.

desc
boolean

Optional. Whether to sort the list in descending order.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "current_page": 0,
  • "page_size": 0,
  • "total_items": 0,
  • "items": [
    ],
  • "total_pages": 0
}

Deletes all email templates associated with a specific account.

Removes all templates linked to the specified account ID. Requires access to the specified account.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}

Send a test email using a specific template

This endpoint allows sending a test email to verify template rendering and delivery.

Request Body schema: application/json; charset=utf-8
required

request payload.

account_id
required
integer <uint64>

Account ID associated with the template and sending request

recipient
required
string

Email address of the recipient who will receive the test email

Must be a valid email address format (e.g., user@example.com)

template_params
any

Optional parameters to be used for template variable substitution

When provided, should be a valid JSON object that matches the template's expected variables. Example: {"name": "John Doe", "order_id": 12345}

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "account_id": 0,
  • "recipient": "string",
  • "template_params": null
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "string",
  • "code": 0
}