🧩 Task Scheduling System
RustMailer includes a built-in task scheduling system. Initially, I created a standalone crate — persistent-scheduler — with the intention of using it directly. However, I later realized that tightly integrating the scheduler into RustMailer would make it easier to support custom features like monitoring and event callbacks. So I embedded the scheduler into the project, removed unnecessary functionality, and tailored it specifically for RustMailer's needs.
🧵 Task Queues
The system defines two main task queues:
OUTBOX_QUEUE– Handles email sending tasks (SmtpTask)EVENTHOOK_QUEUE– Handles event hook dispatch tasks (EventHookTask)
Each queue has its own configurable concurrency via environment variables:
RUSTMAILER_SEND_MAIL_WORKERS– Number of mail sending workers (default:10)RUSTMAILER_EVENT_HOOK_WORKERS– Number of event hook workers (default:10)
🩺 Task Lifecycle & Status
Each task has a lifecycle tracked via the following statuses:
| Status | Description |
|---|---|
Scheduled | Task is scheduled but not yet running |
Running | Task is currently being processed |
Success | Task completed successfully |
Failed | Task failed during execution |
Removed | Task marked for deletion |
Stopped | Task was manually stopped |
Note: Tasks will only be marked as Failed if all retry attempts have been exhausted. Otherwise, failed tasks will be reset to Scheduled and re-queued for another execution attempt. The next execution time is determined according to the configured retry strategy.
🗃 Task Persistence & Storage
- All task metadata is persisted in an embedded database stored as a separate file
tasks.dblocated underRUSTMAILER_ROOT_DIR. - Tasks are fully queryable and support manual inspection as well as status updates.
Related API Endpoints
Hook Tasks
Email Tasks
These endpoints allow you to retrieve task statuses and manage tasks programmatically.
🧹 Cleanup Mechanism
RustMailer includes a built-in cleanup job that runs periodically to remove expired tasks that are no longer needed.
The following task statuses are eligible for cleanup:
RemovedSuccessFailedStopped
This ensures the task store remains clean and efficient over time.
The cleanup interval is controlled by the following configuration:
RUSTMAILER_CLEANUP_INTERVAL_HOURS– Task cleanup interval (default:72hours)
🔄 Retry Policies Overview
RustMailer uses different retry strategies for its two main task types to handle failed executions.
1. Event Hook Tasks (Hook Task)
- Currently uses a fixed Exponential Backoff strategy with retry intervals doubling each time (e.g., 2s, 4s, 8s…).
- Maximum retry attempts: 10.
- This strategy is fixed at the moment and cannot be configured by users. However, based on user feedback, this may be made configurable in future versions.
2. Email Sending Tasks (SMTP Task)
- Users can customize the retry policy when submitting email sending requests.
- Supported strategies:
- Linear: Retries happen at a fixed interval (e.g., every 2 seconds).
- Exponential: Retries happen with exponentially increasing intervals, similar to Hook Tasks.
- Configurable parameters include:
- Retry strategy (Linear or Exponential)
- Base retry interval in seconds
- Maximum number of retry attempts
- If no retry policy is specified, the default is linear retries every 2 seconds, up to 10 attempts.
Summary
| Task Type | Default Retry Strategy | Max Retries | User Configurable |
|---|---|---|---|
| Event Hook Tasks | Exponential backoff (base 2) | 10 | No |
| Email Sending Tasks | Linear (2 seconds interval) | 10 | Yes |
Properly configuring retry policies helps improve reliability for your email sending and event processing while avoiding excessive load from rapid repeated failures.
⏳ Task Delay and Scheduling
- Hook Tasks: By default, event hook tasks execute immediately with no delay (
delay = 0). - Email Sending Tasks: The
send_atfield insend_controlallows scheduling an email to be sent at a specific future time.
The system calculates the delay based on this timestamp and schedules the task accordingly.