Bulk Messaging System

An Electron Desktop app for marketing campaign & broadcast management, using either whatsapp, gmail or a SMTP server

Source

Electron IPC API

Introduction#

IPC handlers the preload bridge exposes to the renderer. Invoke channels for WhatsApp, Gmail, SMTP, and file import, plus the events that stream progress back.

Project structure#

Main process, preload bridge, and renderer stay in their lanes:

Core components#

IPC handler registration#

The main process registers all IPC handlers using ipcMain.handle():

Preload script security model#

The preload script implements a secure contextBridge interface that exposes only necessary functionality:

Architecture overview#

IPC communication flow#

The system implements a unidirectional request-response pattern for handlers and bidirectional event streaming for status updates:

Detailed component analysis#

WhatsApp IPC handlers#

whatsapp-start-client handler#

This handler manages the complete WhatsApp Web client lifecycle:

Handler Registration.

  • Channel: whatsapp-start-client
  • Purpose: Initialize and manage WhatsApp Web client

Parameter Types.

  • No parameters required

Return Value Schema.

javascript
{
 success: boolean,
 message?: string
}

Error Handling Patterns.

  • Client already running detection
  • Initialization failure reporting
  • Authentication error propagation
  • Disconnection monitoring

whatsapp-send-messages handler#

Bulk message sending functionality with clear error handling:

Handler Registration.

  • Channel: whatsapp-send-messages
  • Purpose: Send messages to multiple WhatsApp contacts

Parameter Types.

typescript
interface WhatsAppMessageData {
 contacts: Array<{
 number: string;
 name?: string;
 }>;
 messageText: string;
}

Return Value Schema.

javascript
{
 success: boolean;
 sent: number;
 failed: number;
}

Processing Logic. 1. Validate client readiness 2. Iterate through contacts with personalization 3. Check user registration status 4. Send messages with rate limiting 5. Provide real-time progress updates

whatsapp-import-contacts handler#

Multi-format contact import with validation:

Handler Registration.

  • Channel: whatsapp-import-contacts
  • Purpose: Import contacts from CSV/Text files

Parameter Types.

  • No parameters required

Return Value Schema.

javascript
Array<{
 number: string;
 name?: string;
}> | null

Supported Formats.

  • CSV: Automatic parsing with header detection
  • TXT: Line-by-line parsing with comma separation
  • Error handling for unsupported formats

whatsapp-logout handler#

Secure client logout with cleanup:

Handler Registration.

  • Channel: whatsapp-logout
  • Purpose: Logout from WhatsApp and cleanup resources

Parameter Types.

  • No parameters required

Return Value Schema.

javascript
{
 success: boolean;
 message: string;
}

Cleanup Operations.

  • Client logout attempt
  • Cache directory deletion
  • Authentication directory cleanup
  • Status notification emission

Email IPC handlers#

gmail-auth handler#

OAuth2 authentication flow with browser window:

Handler Registration.

  • Channel: gmail-auth
  • Purpose: Handle Gmail OAuth2 authentication

Parameter Types.

  • No parameters required

Return Value Schema.

javascript
{
 success: boolean;
 error?: string;
}

Authentication Flow. 1. Generate OAuth2 URL with required scopes 2. Open authentication window 3. Handle redirect callbacks 4. Exchange authorization code for tokens 5. Store tokens securely

gmail-token handler#

Token availability checking:

Handler Registration.

  • Channel: gmail-token
  • Purpose: Check if Gmail authentication token exists

Parameter Types.

  • No parameters required

Return Value Schema.

javascript
{
 success: boolean;
 hasToken: boolean;
}

send-email handler#

Bulk email sending via Gmail API:

Handler Registration.

  • Channel: send-email
  • Purpose: Send bulk emails using Gmail API

Parameter Types.

typescript
interface GmailEmailData {
 recipients: string[];
 subject: string;
 message: string;
 delay?: number;
}

Return Value Schema.

javascript
{
 success: boolean;
 results: Array<{
 recipient: string;
 status: 'sent' | 'failed';
 error?: string;
 }>;
}

Progress Events.

  • email-progress events emitted during processing
  • Real-time status updates for each recipient

smtp-send handler#

Bulk email sending via SMTP:

Handler Registration.

  • Channel: smtp-send
  • Purpose: Send bulk emails using SMTP configuration

Parameter Types.

typescript
interface SMTPData {
 smtpConfig: {
 host: string;
 port: number;
 secure: boolean;
 user: string;
 pass: string;
 };
 recipients: string[];
 subject: string;
 message: string;
 delay?: number;
 saveCredentials?: boolean;
}

Return Value Schema.

javascript
{
 success: boolean;
 results: Array<{
 recipient: string;
 status: 'sent' | 'failed';
 error?: string;
 }>;
}

Security Features.

  • Credential encryption with electron-store
  • TLS verification
  • Self-signed certificate support

Event-Driven communication#

WhatsApp status events#

The main process emits status updates to the renderer:

Events Emitted.

  • whatsapp-status: General connection status
  • whatsapp-qr: QR code data URL or null
  • whatsapp-send-status: Message sending progress

Event Flow.

Dependency analysis#

External dependencies#

The application relies on several key external libraries:

Build configuration#

The Vite configuration supports development and production builds:

Build Features.

  • React and Tailwind CSS integration
  • Development server with hot reload
  • Production optimization
  • Cross-platform distribution

Performance considerations#

Rate limiting and throttling#

The system implements multiple layers of rate limiting:

  1. WhatsApp Message Delays. 3-second intervals between messages
  2. Email Delays. Configurable delays between email sends
  3. API Rate Limits. Gmail API quota management
  4. Connection Pooling. Efficient resource use

Memory management#

  • Proper cleanup of event listeners
  • Client session management
  • File descriptor handling
  • Temporary file cleanup

Serialization considerations#

  • All IPC data is serialized automatically
  • Large data structures should be chunked
  • Avoid circular references in IPC payloads
  • Use primitive types for optimal performance

Troubleshooting guide#

Common issues and solutions#

WhatsApp connection problems#

  • QR Code Not Loading. Check network connectivity and restart client
  • Authentication Failures. Verify WhatsApp Web compatibility
  • Client Disconnections. Monitor for network interruptions

Email delivery issues#

  • Gmail Authentication. Verify OAuth2 credentials and API enablement
  • SMTP Configuration. Validate server settings and credentials
  • Rate Limiting. Adjust delay parameters appropriately

IPC communication issues#

  • Function Not Available. Ensure preload bridge is properly loaded
  • Event Listener Cleanup. Verify proper removal of event listeners
  • Memory Leaks. Monitor for accumulated event listeners

Conclusion#

Treat the preload API as the only public surface from the renderer. If a method is missing at runtime, the preload script did not load.