Appwrite Mailer

A script to send personalized HTML emails to all users in an Appwrite project using the Appwrite Messaging service.

Setup

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Configure environment variables in .env file:

   APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
   APPWRITE_PROJECT_ID=your-project-id
   APPWRITE_API_KEY=your-api-key
   EMAIL_SENDER_NAME=Your Application
   EMAIL_SENDER_EMAIL=noreply@yourdomain.com
   EMAIL_SUBJECT=Important Notification
   

   Note: Your API key must have permissions for both Users and Messaging services.

Usage

1. Customize the HTML email template in the templates/email-template.html file.

2. Run in preview mode (default behavior):

   npm start
   

   or

   node send-emails.js
   

3. To launch HTML preview in Google Chrome:

   npm run preview
   

   or

   node send-emails.js --launch
   

4. To list available email templates:

   npm run list-templates
   

   or

   node send-emails.js --list-templates
   

5. To use a specific template:

   npm start -- --template launchMail.html
   

   or

   node send-emails.js --template launchMail.html
   

6. To actually send emails (requires double confirmation):

   npm run send
   

   or

   node send-emails.js --send
   

   You can also specify a template when sending:

   npm run send -- --template launchMail.html
   

Features

• Fetches all users from your Appwrite project (with pagination)
• Reads HTML email template from a file
• Supports multiple template selection (use any HTML template in the templates folder)
• Supports template variables ({{name}}, {{email}}, etc.)
• Preview mode as default behavior (dry run)
• HTML preview in Google Chrome for visual template inspection
• Support for excluding specific emails via a dontSend file
• Statistics for total, ignored, and eligible recipients
• Double confirmation required before sending any emails
• Strong safeguards to prevent accidental email sending
• Real-time progress tracking during email campaign
• Sends personalized HTML emails to each user
• Handles errors gracefully and continues sending to remaining users
• Provides detailed console logs for tracking progress and results

Customizing Email Templates

The default email template is stored in templates/email-template.html. You can modify this HTML file to change the email's appearance and content.

Using Multiple Templates

You can create and use multiple HTML templates in the templates directory.

Interactive Template Selection

When you run the script without specifying a template, it will automatically display a list of available templates and prompt you to choose one:

npm start

This will show something like:

Available email templates:
-------------------------
1. email-template.html (default)
2. launchMail.html

Please select a template by number [1]:

Simply enter the number of the template you want to use and press Enter.

Template Management

To see all available templates without running the script:

npm run list-templates

To explicitly specify a template:

npm start -- --template your-template.html

This allows you to prepare different email campaigns and easily switch between them.

Template Variables

The template supports variable substitution using double curly braces. The following variables are available:

• {{name}}: The user's name (or "User" if not available)
• {{email}}: The user's email address
• {{userId}}: The user's ID in Appwrite

Example template usage:

<h2>Hello {{name}}!</h2>
<p>Your account ({{email}}) has been verified.</p>

Adding Custom Variables

You can add more custom variables by modifying the templateData object in the sendEmailToUser function in send-emails.js:

const templateData = {
    name: user.name || 'User',
    email: user.email,
    userId: user.$id,
    // Add more variables as needed
    customField: user.customField,
    appName: 'Your App Name'
};

Then use them in your template with: {{customField}}, {{appName}}, etc.

Excluding Recipients

You can exclude specific email addresses from the mailing list by creating a dontSend file in the root directory of the project.

Format of the dontSend file

• Each line should contain a single email address to exclude
• Lines starting with # are treated as comments and ignored
• Empty lines are ignored
• Email matching is case-insensitive
• Trailing commas are automatically removed (so CSV files can be used)

Example dontSend file:

# This is a comment and will be ignored
test@example.com
admin@yourdomain.com,  # Trailing comma will be automatically removed
developer@company.com

# You can also add more comments explaining why emails are excluded
unsubscribed@example.com

You can export emails from a spreadsheet to CSV and then use that file after renaming it to dontSend.

Statistics

When running the script, you'll see statistics about ignored emails:

===== EMAIL CAMPAIGN PREVIEW =====
Campaign subject: Important Notification
From: Your Application <noreply@yourdomain.com>
Total users: 1250
  - Users in dontSend list: 5
  - Users without email: 3
Eligible recipients: 1242

Considerations

• Emails are sent sequentially with a small delay to avoid rate limiting
• For large user bases, consider adding more sophisticated error handling and retry logic
• Monitor the Appwrite console to ensure emails are being delivered correctly
• The script automatically creates a plain text version of your HTML email for email clients that don't support HTML
• Review the dontSend file regularly to ensure you're not excluding valid recipients
• The detailed statistics help you understand why some users might not be receiving emails