Professional Python SMTP HTML Mailer for Sequential Email Campaigns

Simple MailShip is a powerful, yet easy-to-use Python application designed to send professional HTML emails sequentially via SMTP. Built with simplicity and reliability in mind, it provides a robust solution for email marketing campaigns, newsletters, notifications, and automated email communications.

Whether you're running a small business, managing a newsletter, or need to send personalized emails to a large list of recipients, Simple MailShip offers the flexibility and features you need while maintaining professional email standards and deliverability best practices.

✨ Key Features

• 📧 HTML Email Templates: Beautiful, responsive email templates with Jinja2 templating support
• 🔄 Sequential Sending: Send emails one by one with customizable rate limiting to avoid spam filters
• 🔒 Secure SMTP: Support for SSL/TLS encryption with Gmail, Outlook, and custom SMTP servers
• 📊 Multiple Authentication: SSL (port 465), STARTTLS (port 587), and no-auth configurations
• 📋 JSON Contact Lists: Load recipients from JSON files with flexible data structure support
• 🎯 Template Variables: Dynamic content insertion using recipient data
• 📱 Mobile-Friendly: Responsive email templates that work across all devices and email clients
• 🛡️ Email Validation: Built-in email address validation and duplicate removal
• ⚡ Rate Limiting: Configurable sending rates to comply with SMTP provider limits
• 🧪 Test Mode: Dry-run capability and single email testing
• 📁 Preview Generation: Save HTML previews of rendered emails before sending
• 🔧 Environment Configuration: Secure credential management via .env files

🚀 Quick Start

Prerequisites

• Python 3.7 or higher
• SMTP server credentials (Gmail App Password recommended)

Installation

1. Clone the repository

   git clone https://github.com/ideacatlab/simple-mailship.git
   cd simple-mailship

2. Create and activate virtual environment

   # Create virtual environment
   python -m venv venv
   
   # Activate virtual environment
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env with your SMTP credentials
   nano .env  # or use your preferred editor

5. Send your first test email

   python mailer.py --test your-email@example.com

⚙️ Configuration

Environment Variables

Simple MailShip uses environment variables for configuration. Copy .env.example to .env and customize the following settings:

SMTP Server Configuration

Variable	Description	Default	Required
SMTP_HOST	SMTP server hostname	smtp.gmail.com	No
SMTP_PORT	SMTP server port	465	No
SMTP_USE_SSL	Use SSL connection	true	No
SMTP_USERNAME	Your email address	-	Yes
SMTP_PASSWORD	Your email password/app password	-	Yes

Email Configuration

Variable	Description	Default	Required
FROM_NAME	Display name for sender	SMTP_USERNAME	No
SUBJECT	Default email subject	-	No
REPLY_TO	Reply-to email address	-	No
TEMPLATE_PATH	Path to HTML template	./templates/example.html	No
RATE_PER_MIN	Emails per minute limit	-	No

SMTP Port Configuration

Simple MailShip supports multiple SMTP configurations:

SSL Connection (Recommended)

• Port: 465
• Security: SSL/TLS encryption from start
• Configuration: SMTP_PORT=465 and SMTP_USE_SSL=true
• Best for: Gmail, most secure option

STARTTLS Connection

• Port: 587
• Security: Starts unencrypted, then upgrades to TLS
• Configuration: SMTP_PORT=587 and SMTP_USE_SSL=false
• Best for: Outlook, some corporate servers

No Authentication (Development Only)

• Port: 25 or custom
• Security: No encryption (not recommended for production)
• Configuration: SMTP_PORT=25 and SMTP_USE_SSL=false
• Best for: Local testing, development servers

Gmail Setup

For Gmail users, follow these steps:

1. Enable 2-Factor Authentication on your Google Account
2. Generate App Password:
   • Go to Google Account Settings
   • Security → 2-Step Verification → App passwords
   • Generate a new app password for "Mail"
3. Use the 16-character app password as SMTP_PASSWORD
4. Set your full Gmail address as SMTP_USERNAME

📋 Usage Examples

Command Line Interface

Simple MailShip provides a comprehensive command-line interface with the following options:

python mailer.py [OPTIONS]

Required Arguments (choose one):

• --test EMAIL: Send a single test email to the specified address
• --list JSON_FILE: Send emails to all recipients in the JSON file

Optional Arguments:

• --subject SUBJECT: Override the default email subject
• --from-name NAME: Override the sender display name
• --reply-to EMAIL: Set a custom reply-to address
• --rate FLOAT: Set rate limit in emails per minute
• --dry-run: Preview what would be sent without actually sending
• --save-previews DIR: Save HTML previews to specified directory
• --verbose: Enable detailed logging

Basic Examples

Send a Test Email

python mailer.py --test john@example.com

Send to Contact List

python mailer.py --list contacts/subscribers.json

Send with Custom Subject and Rate Limiting

python mailer.py --list contacts/newsletter.json --subject "Monthly Newsletter" --rate 10

Dry Run with Preview Generation

python mailer.py --list contacts/campaign.json --dry-run --save-previews ./previews

Send with Custom Reply-To

python mailer.py --list contacts/support.json --reply-to support@company.com --verbose

JSON Contact File Format

Simple MailShip supports flexible JSON formats for contact lists:

Simple List Format

[
  {
    "email": "john@example.com",
    "name": "John Doe",
    "company": "Acme Corp"
  },
  {
    "email": "jane@example.com",
    "name": "Jane Smith",
    "location": "New York"
  }
]

Nested Object Format

{
  "data": [
    {
      "email": "subscriber1@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "subscription_date": "2024-01-15"
    }
  ]
}

Supported Container Keys

• items
• results
• data

Email Field Recognition

Simple MailShip automatically detects email addresses using these field names (case-insensitive):

• email
• e-mail
• mail

Template Variables

All JSON fields are available as template variables in your HTML templates:

<h1>Hello {{name}}!</h1>
<p>Thank you for joining us from {{location}}.</p>
<p>Your email: {{email}}</p>

🎨 Email Templates

Template Structure

Simple MailShip uses Jinja2 templating engine, allowing for dynamic content insertion and conditional logic in your HTML emails.

Basic Template Example

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{subject}}</title>
</head>
<body>
    <h1>Hello {{name|default('Valued Customer')}}!</h1>
    <p>This is a personalized message for {{email}}.</p>
    
    {% if company %}
    <p>We see you're from {{company}}. That's great!</p>
    {% endif %}
    
    <p>Best regards,<br>The Team</p>
</body>
</html>

Advanced Template Features

Conditional Content:

{% if user_type == 'premium' %}
<div class="premium-content">
    <h2>Exclusive Premium Content</h2>
</div>
{% else %}
<div class="standard-content">
    <h2>Standard Content</h2>
</div>
{% endif %}

Loops and Lists:

{% if products %}
<ul>
{% for product in products %}
    <li>{{product.name}} - ${{product.price}}</li>
{% endfor %}
</ul>
{% endif %}

Filters and Formatting:

<p>Welcome {{name|title}}!</p>
<p>Member since: {{join_date|strftime('%B %d, %Y')}}</p>
<p>Total orders: {{order_count|default(0)}}</p>

Email Client Compatibility

The included example template is designed for maximum compatibility:

• Inline CSS: All styles are inlined for better email client support
• Table-based Layout: Uses HTML tables for consistent rendering
• Mobile Responsive: Adapts to different screen sizes
• Dark Mode Support: Includes dark mode media queries
• Outlook Compatibility: Special handling for Microsoft Outlook

Template Best Practices

1. Use Inline CSS: Email clients strip out <style> tags
2. Table Layouts: More reliable than div-based layouts
3. Web-Safe Fonts: Stick to Arial, Helvetica, Georgia, Times
4. Alt Text: Always include alt text for images
5. Test Across Clients: Preview in Gmail, Outlook, Apple Mail
6. Keep It Simple: Complex layouts may break in some clients

🔧 Advanced Configuration

Rate Limiting

Control sending speed to avoid triggering spam filters:

# Send 6 emails per minute (10-second intervals)
python mailer.py --list contacts.json --rate 6

# Very conservative rate (30-second intervals)
python mailer.py --list contacts.json --rate 2

Custom SMTP Providers

Outlook/Hotmail

SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
SMTP_USE_SSL=false
SMTP_USERNAME=your-email@outlook.com
SMTP_PASSWORD=your-password

Yahoo Mail

SMTP_HOST=smtp.mail.yahoo.com
SMTP_PORT=587
SMTP_USE_SSL=false
SMTP_USERNAME=your-email@yahoo.com
SMTP_PASSWORD=your-app-password

Custom SMTP Server

SMTP_HOST=mail.yourcompany.com
SMTP_PORT=465
SMTP_USE_SSL=true
SMTP_USERNAME=noreply@yourcompany.com
SMTP_PASSWORD=your-password

Error Handling

Simple MailShip includes robust error handling:

• Configuration Errors: Missing or invalid environment variables
• Template Errors: Jinja2 template syntax or missing template files
• SMTP Errors: Authentication failures, connection issues
• Email Validation: Invalid email addresses are automatically skipped
• Rate Limiting: Automatic delays between emails

Logging and Monitoring

Enable verbose logging for detailed information:

python mailer.py --list contacts.json --verbose

Output includes:

• Configuration validation
• Template rendering status
• SMTP connection details
• Email sending progress
• Error messages and warnings
• Summary statistics

🧪 Testing and Development

Dry Run Mode

Test your configuration without sending emails:

python mailer.py --list contacts.json --dry-run --save-previews ./test-previews

This will:

• Validate your configuration
• Load and parse contact lists
• Render email templates
• Save HTML previews
• Show what would be sent

Preview Generation

Generate HTML previews for review:

python mailer.py --list contacts.json --save-previews ./previews --dry-run

Previews are saved as:

• preview_test.html (for test emails)
• preview_email@domain.com.html (for list emails)

Single Email Testing

Test with a single recipient:

python mailer.py --test your-email@example.com --save-previews ./test

🤝 Contributing

We welcome contributions from developers of all skill levels! Simple MailShip is an open-source project, and we're excited to collaborate with the community.

How to Contribute

Reporting Issues

• Bug Reports: Use GitHub Issues to report bugs
• Feature Requests: Suggest new features or improvements
• Documentation: Help improve our documentation

Contributing Code

1. Fork the Repository

   git fork https://github.com/ideacatlab/simple-mailship.git

2. Create a Feature Branch

   git checkout -b feature/your-feature-name

3. Make Your Changes

   • Follow existing code style
   • Add tests for new features
   • Update documentation as needed

4. Test Your Changes

   python -m pytest tests/
   python mailer.py --test your-email@example.com --dry-run

5. Submit a Pull Request

   • Provide a clear description of changes
   • Reference any related issues
   • Ensure all tests pass

Development Setup

# Clone your fork
git clone https://github.com/your-username/simple-mailship.git
cd simple-mailship

# Create development environment
python -m venv dev-env
source dev-env/bin/activate  # or dev-env\Scripts\activate on Windows

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # if available

# Run tests
python -m pytest tests/

Code Style Guidelines

• PEP 8: Follow Python PEP 8 style guidelines
• Type Hints: Use type hints for function parameters and return values
• Docstrings: Document functions and classes with clear docstrings
• Error Handling: Include appropriate error handling and logging
• Testing: Write tests for new features and bug fixes

Areas for Contribution

We're particularly interested in contributions for:

• Email Template Library: Additional professional email templates
• SMTP Provider Presets: Configuration presets for popular email providers
• Advanced Features: Attachment support, email tracking, analytics
• Testing: Improved test coverage and integration tests
• Documentation: Tutorials, examples, and improved documentation
• Performance: Optimization for large email lists
• Security: Enhanced security features and best practices

📄 License

Simple MailShip is released under the MIT License. See the LICENSE file for details.

🏢 About TurboCat

Simple MailShip is created and maintained by TurboCat, a web development company specializing in custom software solutions and digital transformation.

TurboCat Services:

• 🌐 Web Development & Design
• ⚙️ Custom Software Development
• ☁️ Infrastructure Management
• 📈 SEO & Digital Marketing
• 🎨 UI/UX Design
• 🔧 Technical Consulting & Support

Visit turbocat.ro to learn more about our services and how we can help transform your digital presence.

🆘 Support

Getting Help

• GitHub Issues: Report bugs and request features
• Documentation: Check this README and code comments
• Community: Join discussions in GitHub Discussions

Common Issues

Gmail Authentication Errors

• Ensure 2-Factor Authentication is enabled
• Use App Password, not your regular password
• Check that "Less secure app access" is disabled

Template Not Found

• Verify TEMPLATE_PATH in your .env file
• Ensure the template file exists and is readable
• Use absolute paths if relative paths don't work

SMTP Connection Issues

• Verify SMTP host and port settings
• Check firewall and network connectivity
• Try different ports (465 for SSL, 587 for STARTTLS)

Rate Limiting

• Reduce sending rate with --rate parameter
• Check your SMTP provider's sending limits
• Consider using dedicated email service for large volumes

---

Made with ❤️ by TurboCat

Transform your email communication with Simple MailShip - the professional Python SMTP solution.