Editor Tutorial

Welcome to the sendMail Editor tutorial. This guide covers how to use the standalone WYSIWYG newsletter editor to create, edit, and manage HTML newsletters.

Getting Started

Prerequisites

  • Python 3.10 or later

  • PyQt6 and PyQt6-WebEngine installed

  • sendMail package installed

Installation

If you haven’t installed sendMail yet:

pip install sendMail

Or from source:

git clone https://github.com/xmayeur/mailing.git
cd mailing
pip install -e .

Launching the Editor

From Command Line

Launch a blank editor:

python src/editor.py

Open an existing file:

python src/editor.py path/to/your/newsletter.md
python src/editor.py path/to/your/newsletter.html

Using the Standalone Binary (macOS/Windows)

If you’ve built the PyInstaller executable:

./dist/sendMailEditor.app/Contents/MacOS/sendMailEditor
./dist/sendMailEditor/sendMailEditor.exe

Creating a New Newsletter

  1. Launch the editor with no arguments

  2. You’ll see a blank document with the rich text editor in the center

  3. Start typing or paste content into the editor

  4. Use the formatting toolbar to style your text:

    • Bold, Italic, ~~Strikethrough~~

    • Heading sizes (H1, H2, H3, etc.)

    • Lists (bullet and numbered)

    • Links and images

    • Blockquotes

    • Code blocks

Opening Existing Documents

The editor supports both Markdown and HTML:

# Open a Markdown file
python src/editor.py newsletters/2026-05-17.md

# Open an HTML file
python src/editor.py newsletters/template.html

When you open a file, the editor automatically detects the format and displays it in the rich text editor.

Editing Content

Text Formatting

Use the Quill editor toolbar to format text:

  1. Emphasis: Select text and click Bold (B) or Italic (I)

  2. Headings: Select text and choose heading size from dropdown

  3. Lists: Click the bullet list or number list button

  4. Links: Select text, click the link button, enter URL

  5. Images: Click the image button and choose from your computer

Inserting Images

  1. Click the image button in the toolbar

  2. Select an image from your computer

  3. The image is automatically embedded as base64 for HTML export

HTML Preview

The editor shows a live preview of the generated HTML. This helps you see how the newsletter will look when sent.

Working with Filters

The editor includes advanced filtering capabilities for conditional content delivery.

Opening the Send Dialog

  1. Click File → Send or use Ctrl+S (or Cmd+S on macOS)

  2. This opens the Send Dialog with filter options

  3. The dialog shows your current sendMail profiles

Setting Up Filters

  1. In the Filters section, enter YAML syntax:

    country: USA
subscription_level: premium

  2. Click Apply Filter to activate the filter

  3. The editor validates the filter syntax in real-time

  4. A visual indicator shows if the filter is valid (green) or invalid (red)

Database Preview

  1. Select a subscriber database (CSV or Google Sheets)

  2. Click Load Database to preview records

  3. The editor shows matching records based on your filter

  4. See exactly which subscribers will receive the filtered content

Valid Filter Fields

Filter fields depend on your subscriber database schema. Common fields include:

  • country

  • email

  • subscription_level

  • name

  • Custom fields from your CSV/Google Sheets

Managing Profiles

Adding sendMail Profiles

The editor reads profiles from your config.yml:

profiles:
  newsletter:
    smtp_server: smtp.gmail.com
    from_address: newsletters@example.com
    rate_limit: 100

Selecting a Profile

  1. Open the Send Dialog (File → Send)

  2. The Profile dropdown shows all available profiles

  3. Select the profile to use for sending

  4. The filter fields are validated against that profile’s database

Profile Configuration

Profiles are managed in your sendMail configuration file:

# Edit your configuration
python src/editor.py
# Then: File → Settings

Saving Your Work

The editor automatically saves your content in two formats:

Markdown Format

The native format for storing content. Includes:

  • Human-readable text formatting

  • Preserved structure (headings, lists, etc.)

  • Easy version control in Git

HTML Format

The format used for sending emails. Includes:

  • Rendered HTML markup

  • Embedded images as base64

  • Styling and formatting preserved

Save Behavior

When you edit a document, both formats are updated:

New documents: Saved with your chosen filename:

python src/editor.py newsletters/my-newsletter.md
# Creates: newsletters/my-newsletter.md (Markdown)
#          newsletters/my-newsletter.html (HTML)

Existing documents: Updated in place:

# Both .md and .html files are updated

Manual Save

Use File → Save (Ctrl+S / Cmd+S) to explicitly save changes.

Sending via sendMail

Once your newsletter is ready:

  1. Save the newsletter in the editor

  2. Note the HTML file path (e.g., newsletters/2026-05-17.html)

  3. Send via sendMail:

    python src/sendMail.py --profile newsletter \
  -s "May Newsletter 2026" \
  newsletters/2026-05-17.html

With Filters

Apply the same filter used in the editor:

python src/sendMail.py --profile newsletter \
  -s "Premium Subscribers Newsletter" \
  -f 'subscription_level: premium' \
  newsletters/2026-05-17.html

Using Database Preview Filter

  1. Set up filter in editor

  2. Copy the filter from the editor

  3. Use the same filter in sendMail command

Tips and Tricks

Templates

Create reusable newsletter templates:

# Save as a template
python src/editor.py templates/base-newsletter.md

# Create new newsletter from template
cp templates/base-newsletter.md newsletters/2026-05-20.md
python src/editor.py newsletters/2026-05-20.md

Batch Processing

For recurring newsletters:

# Create a weekly newsletter
python src/editor.py newsletters/weekly-$(date +%Y-%m-%d).md

# Send when ready
python src/sendMail.py --profile newsletter \
  -s "Weekly Update" \
  newsletters/weekly-$(date +%Y-%m-%d).html

Filter Testing

Before sending to your full list:

  1. Create a test filter in the editor

  2. Use database preview to see matching records

  3. Test with a small group first:

    python src/sendMail.py --profile newsletter \
  -s "Test Newsletter" \
  -f 'test_user: true' \
  -t \
  newsletters/test.html

Image Best Practices

  1. Size appropriately: Compress images before inserting

  2. Alt text: Always provide alt text for accessibility

  3. Responsive: The editor scales images to fit email widths

  4. Test rendering: Preview in the HTML pane before sending

Markdown Tips

The editor supports full GitHub-flavored Markdown:

  • Tables

  • Code blocks with syntax highlighting

  • Links and references

  • Inline HTML (for advanced formatting)

Google Sheets Integration

To use Google Sheets for subscriber lists:

  1. Set up Google Sheets credentials in sendMail config

  2. In the editor, select your Google Sheets database

  3. Use database preview to verify filters work correctly

Common Tasks

Create and Send a Simple Newsletter

# 1. Create new newsletter
python src/editor.py newsletters/announcement.md

# 2. Edit in the editor GUI
# (Add your content and format it)

# 3. Send to all subscribers
python src/sendMail.py --profile default \
  -s "Important Announcement" \
  newsletters/announcement.html

Send to Filtered Group

# 1. Create newsletter
python src/editor.py newsletters/premium-offer.md

# 2. Set up filter in editor
# Filter: subscription_level: premium

# 3. Test with preview
# (Verify matching records in database preview)

# 4. Send to filtered group
python src/sendMail.py --profile default \
  -s "Exclusive Premium Offer" \
  -f 'subscription_level: premium' \
  newsletters/premium-offer.html

Create Newsletter from Template

# Copy template
cp templates/newsletter-template.md newsletters/2026-05-18.md

# Open in editor
python src/editor.py newsletters/2026-05-18.md

# Customize content and send
python src/sendMail.py --profile newsletter \
  -s "Weekly Newsletter" \
  newsletters/2026-05-18.html

Troubleshooting

Editor Won’t Launch

  • Verify PyQt6 is installed: pip install PyQt6 PyQt6-WebEngine

  • Check Python version: python --version (requires 3.10+)

  • On Linux without display: Use xvfb or set QT_QPA_PLATFORM=offscreen

Filter Not Validating

  • Check YAML syntax (proper indentation with spaces, not tabs)

  • Ensure field names match your database schema

  • Look for validation error message in red

Images Not Embedding

  • Check image file path is correct

  • Large images may be scaled down for email compatibility

  • Some email clients strip images - always provide alt text

sendMail Command Not Found

  • Ensure sendMail is installed: pip install sendMail

  • Or use full path: python src/sendMail.py