Multi-threading

Multi-threading allows your system to execute multiple tasks concurrently, improving performance and efficiency. By running processes in parallel, you can reduce execution time and handle complex operations more effectively, ensuring faster processing of tasks such as email sending, data imports, or system updates.

Overview

Multi-threading enables parallel email processing:

+------------------+
|  EMAIL QUEUE     |
|  (pending emails)|
+------------------+
         |
         +---------+---------+---------+---------+
         |         |         |         |         |
         v         v         v         v         v
    +--------+ +--------+ +--------+ +--------+ +--------+
    |Thread 1| |Thread 2| |Thread 3| |Thread 4| |Thread N|
    +--------+ +--------+ +--------+ +--------+ +--------+
         |         |         |         |         |
         v         v         v         v         v
+----------------------------------------------------------+
|                    SENDING NODES                          |
+----------------------------------------------------------+

---

Why Multi-threading Matters

Performance

• Increased throughput - Send more emails per hour
• Parallel processing - Multiple connections simultaneously
• Reduced latency - Don't wait for sequential processing

Scalability

• Handle large lists - Process millions of contacts efficiently
• Meet deadlines - Complete time-sensitive campaigns faster
• Maximize resources - Utilize server capacity effectively

Efficiency

• Optimal resource use - Balance CPU and network usage
• Queue management - Process backlog faster
• Node utilization - Distribute load across sending nodes

---

Multi-threading Settings

Navigate to Setup → Multi-threading to configure the default thread settings.

Settings Form

Field	Description
Status	Enable or disable multi-threading to allow users to run tasks concurrently
Default number of threads to show	The default thread count displayed when scheduling campaigns

Status

Toggle to enable or disable multi-threading system-wide.

Status	Description
Enabled	Multi-threading options appear during campaign scheduling
Disabled	Single-threaded processing only

Default Number of Threads to Show

Select the default number of threads to suggest as a recommendation during the campaign scheduling process.

Default Value Only

This setting controls the default value shown in the threads dropdown when scheduling a campaign. Users can still change this value during scheduling based on their needs and permissions.

Saving Settings

Click Save to apply the multi-threading configuration.

---

Thread Limits

Thread usage can be controlled at multiple levels:

System-Wide Limit (.env)

Set a maximum thread limit for the entire system in your .env file:

MAX_THREADS=10

This limits the maximum threads available system-wide, regardless of other settings.

Per-User Limit

Limit the maximum threads a specific administrator can use:

1. Navigate to Setup → Staff Management → Administrators
2. Click Add New or Edit an existing administrator
3. Enable the Maximum threads toggle
4. Enter the maximum number of threads for this user

Setting	Description
Maximum threads (toggle)	Enable to set a thread limit for this user
Maximum threads (value)	The maximum threads this user can select when scheduling

When enabled, this user will not be able to select more threads than the specified limit, even if the system default is higher.

Resource Management

Use per-user thread limits to:

• Prevent resource overuse by individual users
• Allocate more threads to high-priority campaigns
• Balance system load across multiple administrators

---

Campaign Scheduling

When scheduling a campaign, the threads dropdown:

1. Shows the default value configured in Multi-threading Settings
2. Allows users to change the value based on their needs
3. Respects the user's maximum threads limit if configured
4. Respects the system-wide MAX_THREADS environment variable

Thread Selection During Scheduling

Factor	Effect
Multi-threading disabled	Thread selection not available
Default threads setting	Pre-selected value in dropdown
User's maximum limit	Caps available options
System MAX_THREADS	Overall system cap

---

How Multi-threading Works

Queue Processing

1. Campaign is scheduled with a specific thread count
2. Multiple worker processes start based on thread count
3. Each worker claims a batch of emails from the queue
4. Workers send emails in parallel through sending nodes
5. Results are recorded for each batch
6. Workers claim next batch until queue is empty

Load Distribution

When using multiple sending nodes:

• Emails are distributed across available nodes
• Each thread can use different nodes based on rotation
• Load balancing ensures even distribution

Failure Handling

• Failed emails are returned to queue for retry
• Retry logic handles temporary failures
• Error logging captures issues for troubleshooting

---

Performance Recommendations

Recommended Thread Count by Server Type

Server Type	Recommended Threads
Shared hosting	1-2
VPS (1-2 CPU cores)	2-4
VPS (4+ CPU cores)	4-8
Dedicated server	8-16+

Calculating Optimal Threads

A general guideline:

Recommended Threads = (Available CPU Cores) × 2

Example:

• 4 CPU cores → up to 8 threads
• Start with a lower value and increase gradually

Resource Consideration

More threads require more server resources (CPU, RAM, network connections). Monitor server performance when increasing threads. A warning appears when selecting 10 or more threads.

Server Requirements by Thread Count

Threads	Minimum RAM	CPU Cores
1-2	1GB	1
2-4	2GB	2
4-8	4GB	4
8-16	8GB+	8+

---

Best Practices

Configuration

• Start conservative - Begin with fewer threads and increase gradually
• Monitor resources - Watch CPU and memory usage when adjusting
• Match to capacity - Don't exceed your server's capabilities
• Test before production - Verify stability with test campaigns

User Management

• Set appropriate limits - Configure per-user limits based on needs
• Balance allocation - Distribute thread capacity fairly
• Review periodically - Adjust limits as usage patterns change

Performance

• Optimize database - Ensure database can handle concurrent connections
• Use SSD storage - Faster disk I/O improves queue processing
• Monitor queue depth - Watch for backlog buildup
• Check sending nodes - Ensure nodes can handle the connection load

---

Troubleshooting

Slow Sending Despite Multiple Threads

Possible causes:

• Sending node bottleneck
• Database connection limits
• Network latency
• Insufficient server resources

Solutions:

• Add more sending nodes
• Increase database connection pool
• Check network connectivity
• Upgrade server resources

User Cannot Select Higher Thread Count

Possible causes:

• User has a maximum threads limit set
• System MAX_THREADS environment variable is limiting
• Multi-threading is disabled

Solutions:

• Check user's administrator settings for thread limit
• Review .env file for MAX_THREADS setting
• Enable multi-threading in settings

High Server Resource Usage

Possible causes:

• Too many threads configured
• Large email batches
• Inefficient sending nodes

Solutions:

• Reduce thread count
• Optimize batch sizes
• Review sending node performance
• Consider upgrading server

Queue Not Processing

Possible causes:

• Cron jobs not running
• Queue workers stopped
• Database connectivity issues

Solutions:

• Verify cron configuration
• Check queue worker status
• Test database connection

---

Related Settings

Setting	Location	Purpose
Default threads	Setup → Multi-threading	System default for scheduling
Maximum threads	Administrator form	Per-user thread limit
MAX_THREADS	.env file	System-wide maximum
Sending node limits	Setup → Sending Nodes	Per-node hourly limits

---

Next Steps

• Staff Management - Configure per-user thread limits
• Sending Nodes - Set up email sending infrastructure
• Broadcasts - Schedule campaigns with multi-threading