1. Getting Started

Welcome to NeuroMail!

NeuroMail is an AI-powered email marketing platform that helps you send the right message at the right time. This guide will walk you through everything you need to know.

Quick Setup (5 minutes)

1. Create your account at /register
2. Import your first contacts via CSV or API
3. Choose a template from our library
4. Create your first campaign
5. Send! Our AI handles the rest

What's Included

2. Dashboard Overview

Your dashboard is mission control for all your email marketing. Here's what you'll find:

Key Metrics

• Total Contacts: All contacts in your database
• Active Contacts: Contacts who can receive emails (not bounced or unsubscribed)
• Campaigns: Number of campaigns you've created
• Contact Groups: How many groups you've organized
• Monthly Usage: Emails sent vs. your 5,000 monthly limit

Recent Contacts Table

See your latest contacts with:

• Email & Name: Contact details
• Engagement Score: 0-100 rating (higher = more engaged)
• Status: Active, Bounced, or Unsubscribed
• Groups: Which groups they belong to
• Date Added: When they joined your list

Quick Actions

Fast access to common tasks:

• New Campaign: Start creating an email
• Add Contact: Manually add someone
• View All Contacts: See your full list
• Import CSV: Bulk upload contacts

3. Managing Contacts

Adding Contacts

There are 4 ways to add contacts to NeuroMail:

Method 1: Manual Entry

1. Go to Contacts → Add Contact
2. Enter email, first name, last name (required)
3. Optional: phone number, organization, persona
4. Click Add Contact

Method 2: CSV Import

1. Prepare a CSV file with columns: email, first_name, last_name
2. Go to Contacts → Import CSV
3. Upload your file
4. Map columns if needed
5. Click Import

email,first_name,last_name,phone,organization
john@example.com,John,Doe,+1234567890,Acme Corp
jane@example.com,Jane,Smith,+0987654321,Tech Inc

Method 3: API Integration

Connect your website or app to automatically add contacts. See API Integration section below.

Method 4: QR Code Pages

Let people subscribe by scanning a QR code. See QR Code Pages section below.

Contact Fields

• Email: Required, must be valid
• First & Last Name: Required
• Phone: Optional
• Organization: Optional company name
• Customer Persona: Entrepreneur, Corporate, Student, or Freelancer (affects AI predictions)
• Status: Active, Bounced, or Unsubscribed (managed automatically)
• Source: How they were added (manual, CSV, API, QR code)

Email Validation

NeuroMail automatically:

• Validates email format
• Detects common typos (e.g., gmai.com → gmail.com)
• Suggests corrections before importing
• Prevents duplicate emails

Engagement Score (0-100)

Every contact gets an AI-calculated engagement score based on:

• Open Rate (35%): How often they open your emails
• Click Rate (25%): How often they click links (weighted 2x)
• Recency (20%): How recently they engaged
• Frequency (15%): How often they engage
• Bounce Penalty (5%): Deductions for bounces

Score Ranges:

• 75-100 (High): Super engaged, send them more!
• 50-74 (Medium): Moderately interested
• 0-49 (Low): Consider re-engagement campaigns

4. Contact Groups

Groups let you organize contacts for targeted campaigns.

Creating Groups

1. Go to Groups → Create Group
2. Enter a name (e.g., "Newsletter Subscribers", "VIP Customers")
3. Optional: Add a description
4. Click Create

Adding Contacts to Groups

Two ways to add contacts:

During Contact Creation

Select groups when manually adding a contact or during CSV import.

From Contact List

1. Go to Contacts
2. Click on a contact
3. Select Add to Group
4. Choose group(s)

Group Stats

Each group shows:

• Total Contacts: All contacts in the group
• Active Contacts: Only those who can receive emails

Using Groups in Campaigns

When creating a campaign, select which group(s) should receive it. This lets you send targeted messages to specific audiences.

5. Email Templates

NeuroMail includes 20 professionally designed templates ready to use.

Template Categories

• Newsletter: Regular updates and content roundups
• Promotional: Sales, offers, and special deals
• Welcome: First-time subscriber greetings
• Announcement: Product launches and news
• Event: Webinars, conferences, and invitations
• Follow-up: Personal check-ins and nurture emails

Using Templates

1. Go to Templates
2. Browse available templates
3. Click Use This Template on your favorite
4. Customize the content (see below)
5. Preview and send!

Template Editor

Each template has customizable placeholders:

• - Your business name
• - Main headline
• - Body content
• - Button text
• - Button link
• And more depending on the template

Live Preview

As you fill in placeholders, see a real-time preview of your email. Toggle between desktop and mobile views to ensure it looks great everywhere.

6. Creating Campaigns

Step-by-Step Campaign Creation

Step 1: Choose a Template

Start at Templates and select one that fits your message.

Step 2: Customize Content

• Campaign Name: Internal name (not seen by recipients)
• Subject Line: What recipients see in their inbox
• Content: Fill in all template placeholders
• Target Groups: Select which contact groups receive this email

Step 3: Smart Timing (Optional)

Enable Smart Timing to let AI determine the best send time for each contact. If disabled, emails send immediately.

Step 4: Spam Check

Before sending, NeuroMail analyzes your content for:

• Spam trigger words
• Excessive caps or punctuation
• Missing unsubscribe link (automatically added)
• Suspicious links

Spam Score Thresholds:

• 0-49: ✅ Good to send
• 50-79: ⚠️ Warning (can still send with caution)
• 80+: ❌ Blocked (fix issues before sending)

Step 5: Review & Send

After creating your campaign, review all details on the campaign detail page. When ready, click Send Campaign Now.

Campaign Statuses

• Draft: Created but not sent yet
• Sending: Currently being sent (background processing)
• Sent: Completed
• Paused: Stopped mid-send (rare)

Monthly Limits

Your plan includes 5,000 emails per month. This resets on the 1st of each month. Monitor your usage on the dashboard.

7. AI Features

NeuroMail uses artificial intelligence to maximize your email performance.

Smart Send-Time Optimization

Our AI analyzes when each contact historically opens emails and predicts their optimal send time.

How It Works:

1. AI learns from historical open times (requires at least 5 past opens)
2. Considers the contact's customer persona (Entrepreneur, Corporate, Student, Freelancer)
3. Predicts the best hour to send for maximum open rate
4. Schedules emails individually for each contact

Persona-Based Fallbacks:

If not enough data exists, AI uses smart defaults:

• Entrepreneur: 8:00 AM (early morning)
• Corporate: 10:00 AM (mid-morning at work)
• Student: 2:00 PM (afternoon)
• Freelancer: 11:00 AM (flexible schedule)

Engagement Scoring

Every contact gets a 0-100 engagement score calculated by AI based on:

• Historical open rates
• Click behavior (weighted heavily)
• Recency of engagement
• Frequency of engagement
• Bounce history

Use these scores to:

• Identify your most engaged subscribers
• Target re-engagement campaigns at low scorers
• Segment contacts by engagement level

AI Content Generation

Generate email content instantly using AI (powered by Google Gemini).

How to Use:

1. Open any template in the editor
2. Click Generate with AI
3. Enter a prompt describing what you want (e.g., "Promote our new fitness app to busy professionals")
4. Select a tone: Professional, Friendly, Casual, or Urgent
5. Click Generate
6. AI fills all template placeholders automatically
7. Review and edit as needed

Spam Content Detection

AI analyzes your email content before sending to detect:

• Spam trigger words and phrases
• Patterns that might harm deliverability
• Missing required elements (like unsubscribe links)
• Suspicious or malicious links

Emails with high spam scores (80+) are automatically blocked with suggestions for fixes.

Bounce Risk Prediction

AI predicts which contacts are likely to bounce based on:

• Email domain reputation
• Contact engagement history
• Previous bounce patterns

High-risk contacts may be automatically removed to protect your sender reputation.

8. Analytics & Tracking

Campaign Analytics

Track your campaign performance with detailed metrics:

Key Metrics

• Recipients: Total contacts who received the email
• Sent: Successfully delivered emails
• Opens: How many times your email was opened
• Clicks: How many times links were clicked
• Bounces: Emails that couldn't be delivered

Rates

• Open Rate: (Opens / Sent) × 100
• Click Rate: (Clicks / Sent) × 100
• Click-to-Open Rate: (Clicks / Opens) × 100
• Bounce Rate: (Bounces / Sent) × 100

How Tracking Works

Open Tracking

A tiny 1x1 transparent pixel is embedded in each email. When a recipient opens the email and loads images, the pixel registers an "open" event.

Click Tracking

All links in your email are automatically wrapped with tracking URLs. When someone clicks, we record it and redirect them to the actual destination instantly.

Email Logs

View individual email status for each contact:

• Queued: Scheduled to send
• Sending: Currently being sent
• Sent: Successfully delivered
• Opened: Recipient opened the email
• Clicked: Recipient clicked a link
• Bounced: Email couldn't be delivered

Contact-Level Analytics

Every contact has lifetime stats:

• Total Emails Sent: How many campaigns they received
• Total Opens: Cumulative opens across all campaigns
• Total Clicks: Cumulative clicks
• Last Opened: Most recent engagement date
• Engagement Score: AI-calculated score (0-100)

Unsubscribes

Every email includes an unsubscribe link (required by law). When someone unsubscribes:

1. They're immediately marked as "Unsubscribed"
2. They won't receive future campaigns
3. They see a confirmation page
4. You're notified via dashboard stats

9. API Integration

Connect your website, app, or service to NeuroMail via our API.

Getting Your API Key

1. Log in to NeuroMail
2. Go to API Settings
3. Copy your unique API key (it looks like: a1b2c3d4-e5f6-7890...)

API Endpoint

Add contacts via webhook:

POST /api/webhook/<YOUR_API_KEY>/contact/

Request Format (JSON)

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",          // Optional
  "organization": "Acme Corp",     // Optional
  "group_name": "Newsletter"       // Optional
}

Response (Success)

{
  "success": true,
  "contact_id": 123,
  "email": "john@example.com",
  "created": true,
  "message": "Contact added successfully"
}

Response (Error)

{
  "success": false,
  "error": "Invalid email address",
  "issues": ["Email format is invalid"]
}

Example Integration (HTML Form)

<form id="subscribe-form">
  <input type="email" name="email" placeholder="Your email" required>
  <input type="text" name="first_name" placeholder="First name" required>
  <input type="text" name="last_name" placeholder="Last name" required>
  <button type="submit">Subscribe</button>
</form>

<script>
document.getElementById('subscribe-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const formData = new FormData(e.target);
  const data = {
    email: formData.get('email'),
    first_name: formData.get('first_name'),
    last_name: formData.get('last_name'),
    group_name: 'Newsletter'
  };
  
  const response = await fetch('/api/webhook/YOUR_API_KEY/contact/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  
  const result = await response.json();
  if (result.success) {
    alert('Subscribed successfully!');
  } else {
    alert('Error: ' + result.error);
  }
});
</script>

Email Validation & Auto-Correction

The API automatically:

• Validates email format
• Corrects common typos (e.g., gmai.com → gmail.com)
• Returns a warning if auto-corrected
• Prevents duplicate emails

Rate Limits

• Rate: 100 requests per hour per API key
• Burst: Up to 10 requests per minute
• Exceeded limits return HTTP 429 (Too Many Requests)

Testing Your API Key

Test endpoint (no data needed):

GET /api/webhook/<YOUR_API_KEY>/test/

Returns:

{
  "success": true,
  "message": "API key is valid",
  "user": "yourname",
  "email": "your@email.com",
  "monthly_limit": 5000,
  "sent_this_month": 142
}

10. QR Code Subscription Pages

Let people subscribe by scanning a QR code—perfect for physical locations, events, or print materials.

Setting Up Your QR Code Page

1. Go to API Settings
2. Find the QR Code Subscription section
3. Customize your page:
   • Title: What's your business? (e.g., "Join Our Newsletter")
   • Description: What subscribers get (e.g., "Get weekly tips and exclusive offers")
   • Button Text: CTA text (e.g., "Subscribe Now")
4. Click Save Changes

Downloading Your QR Code

1. Click Download QR Code
2. Save the PNG image
3. Print it or add it to your materials

How It Works

1. Someone scans your QR code with their phone
2. They're taken to your custom subscription page
3. They enter their email, first name, and last name
4. They click Subscribe
5. They're added to your contacts automatically
6. They're also added to a special group: "QR Code Subscribers"
7. They see a success confirmation

QR Code Page URL

Your unique subscription page:

/subscribe/<YOUR_API_KEY>/

You can also share this link directly (no QR code needed).

Use Cases

• Retail Stores: Display at checkout or on products
• Events: Print on posters, badges, or banners
• Business Cards: Add to your card design
• Print Ads: Include in magazines or flyers
• Restaurants: Table tents or menus
• Packaging: Product boxes or inserts

Tracking QR Subscribers

All QR code subscribers:

• Have source: 'qr_code' in their profile
• Are automatically added to "QR Code Subscribers" group
• Can be filtered and targeted separately

11. Best Practices

Email Marketing Tips

Subject Lines

• Keep it under 60 characters
• Create urgency or curiosity
• Avoid spam words ("Free", "Act Now", "Click Here")
• Personalize when possible
• Test different approaches

Email Content

• Keep emails focused on one main message
• Use short paragraphs (2-3 sentences max)
• Include a clear call-to-action (CTA)
• Make CTAs stand out visually
• Use images sparingly (text-to-image ratio 60:40)
• Always preview on mobile before sending

Sending Schedule

• Use Smart Timing for best results
• Don't send too frequently (2-4x per month is ideal for most)
• Be consistent (same day/time helps builds expectations)
• Avoid weekends unless your audience expects it

List Hygiene

• Remove bounced contacts promptly
• Honor unsubscribes immediately
• Don't buy email lists (seriously, never)
• Segment inactive contacts and try re-engagement campaigns
• Remove contacts who haven't engaged in 6+ months

Compliance

CAN-SPAM Act (USA)

• Include your physical address (business or P.O. Box)
• Provide a clear unsubscribe link (NeuroMail does this automatically)
• Honor unsubscribe requests within 10 days
• Use accurate subject lines and sender info

GDPR (EU)

• Only email people who gave explicit consent
• Keep records of how you got consent
• Allow people to access, correct, or delete their data
• Don't send emails to EU residents without consent

Deliverability Tips

• Warm up your sender reputation gradually (start small, increase slowly)
• Keep bounce rate under 5%
• Avoid spam trigger words
• Don't use all caps or excessive punctuation!!!
• Include both text and HTML versions
• Don't use URL shorteners (bit.ly, tinyurl, etc.)
• Authenticate your domain (if using custom FROM email)

Engagement Strategies

Segmentation

Send targeted messages based on:

• Engagement level (high, medium, low scorers)
• Customer persona
• Behavior (clicked specific links, opened certain campaigns)
• Demographics (if you have that data)

Re-Engagement Campaigns

For contacts with low engagement scores (0-49):

• Send a "We Miss You" email
• Offer exclusive content or discounts
• Ask for feedback on why they're not engaging
• Make it easy to unsubscribe (better to let them go than hurt your sender reputation)

12. Troubleshooting

Common Issues & Solutions

Problem: My emails aren't sending

Possible causes:

• Monthly limit reached: Check dashboard—you may have hit your 5,000 email limit
• No active contacts: Make sure your target groups have active contacts
• High spam score: Your content may be blocked—check the spam checker feedback
• Payment issue: Verify your subscription is active

Problem: Low open rates

Try these fixes:

• Improve your subject lines (test different approaches)
• Enable Smart Timing to optimize send times
• Clean your list (remove inactive contacts)
• Make sure your FROM name is recognizable
• Segment your audience and send targeted content

Problem: High bounce rate

Solutions:

• Validate emails before importing (use NeuroMail's auto-validation)
• Remove bounced contacts immediately
• Check for typos in email addresses
• Don't buy or scrape email lists

Problem: Emails going to spam

Fixes:

• Reduce spam trigger words
• Don't use all caps or excessive punctuation
• Keep a good text-to-image ratio (60% text, 40% images)
• Avoid URL shorteners
• Make sure recipients consented to emails
• Maintain a clean list (low bounce rate)

Problem: Can't import CSV

Check these:

• File must be .csv format
• Must have email column
• Emails must be valid format
• File size under 10MB
• UTF-8 encoding recommended

Problem: API key not working

Verify:

• Copied entire API key (they're long!)
• No extra spaces before/after the key
• Using correct endpoint URL
• Sending proper JSON format
• Not hitting rate limits (100/hour)

Getting Help

Still stuck? Contact us:

• Email: emailengine2026@gmail.com
• Response time: Usually within 24 hours