============================================================
MailFlow - User Guide
============================================================

Welcome to MailFlow! This guide explains how to use every
feature of your email marketing and automation system.

------------------------------------------------------------
GETTING STARTED
------------------------------------------------------------

After logging in, you'll see your Dashboard showing:
  - Active Contacts count
  - Total Campaigns
  - Emails Sent
  - Emails in Queue
  - Active Automations
  - Total Tags

The sidebar on the left takes you to every section.

FIRST STEPS (do these in order):
  1. Go to SMTP Settings and set up your email server
  2. Test your SMTP by sending a test email
  3. Go to Tags and create some tags (optional but useful)
  4. Go to Contacts and add contacts (or import from CSV)
  5. Create your first Campaign
  6. Send or schedule the campaign

------------------------------------------------------------
SMTP SETTINGS
------------------------------------------------------------

Before you can send any emails, you must configure your
SMTP server. SMTP is the protocol used to send emails.

Go to: SMTP Settings (gear icon in sidebar)

Fill in:
  - SMTP Host: The mail server address (e.g., smtp.gmail.com)
  - Port: Usually 587 for TLS, 465 for SSL
  - Username: Your email username (usually your full email)
  - Password: Your email password or App Password
  - Encryption: TLS is recommended
  - From Name: The name that appears in recipients' inboxes
  - From Email: The email address emails come from
  - Reply-To: Where replies go (can be the same as From Email)

COMMON SMTP SETTINGS:
  Gmail:     smtp.gmail.com, port 587, TLS
  Outlook:   smtp-mail.outlook.com, port 587, TLS
  SendGrid:  smtp.sendgrid.net, port 587, TLS
  Mailgun:   smtp.mailgun.org, port 587, TLS

GMAIL NOTE: You need an "App Password" not your regular password.
  1. Enable 2-Factor Authentication in your Google account
  2. Go to Google Account > Security > App passwords
  3. Create an app password for "Mail"
  4. Use that 16-character code as your SMTP password

After saving, use the "Send Test Email" section to verify
your settings are working correctly.

------------------------------------------------------------
TAGS
------------------------------------------------------------

Tags are labels you can apply to contacts to group and
segment them. Examples: "Newsletter", "Customers", "VIP",
"Leads", "Webinar Attendees"

CREATING A TAG:
  1. Click "Tags" in the sidebar
  2. Click "New Tag"
  3. Enter a name and pick a color
  4. Click Create

USING TAGS:
  - Assign tags to contacts on the contact edit page
  - Filter contacts by tag on the Contacts page
  - Target campaigns to specific tags
  - Use tags as automation triggers

DELETING A TAG:
  Deleting a tag removes it from all contacts. The contacts
  themselves are not deleted.

------------------------------------------------------------
CONTACTS
------------------------------------------------------------

ADDING A CONTACT:
  1. Click "Contacts" in the sidebar
  2. Click "Add Contact"
  3. Enter email (required), first name, last name
  4. Set status: Active = will receive emails
  5. Check any tags to assign
  6. Click Save Contact

CONTACT STATUS:
  - Active: Contact will receive emails
  - Unsubscribed: Contact will be skipped when sending
  - Bounced: Contact will be skipped when sending

SEARCHING & FILTERING:
  On the Contacts page you can:
  - Search by name or email
  - Filter by tag
  - Filter by status
  - Click Filter button to apply

BULK ACTIONS:
  1. Tick the checkboxes next to contacts (or use "Select All")
  2. Choose an action from the dropdown at the bottom
  3. Click Apply
  Actions: Activate, Unsubscribe, Delete

IMPORTING CONTACTS FROM CSV:
  1. Click "Import CSV" on the Contacts page
  2. Prepare your CSV file with these columns:
     email, first_name, last_name
     (The first row must be the column headers)
  3. Choose the file and optionally select tags
  4. Click Import
  
  Duplicate emails are skipped automatically.
  Max file size: 5MB

------------------------------------------------------------
CAMPAIGNS
------------------------------------------------------------

A campaign is an email you send to a group of contacts.

CREATING A CAMPAIGN:
  1. Click "Campaigns" in the sidebar
  2. Click "New Campaign"
  3. Fill in:
     - Campaign Name: Your internal label (not shown to recipients)
     - Email Subject: The subject line recipients see
     - From Name: Your name as it appears in their inbox
     - From Email: Must be a valid email that your SMTP can send from
     - Reply-To: Where replies will go
     - HTML Body: Your email content (can include HTML formatting)
     - Plain Text Body: Optional plain text version
  4. Under "Recipients", check tags to filter who receives it.
     Leave all unchecked to send to ALL active contacts.
  5. Click "Save Draft"

MERGE TAGS - Personalising Emails:
  You can use these special codes in your subject and body:
    {{first_name}} - Replaced with contact's first name
    {{last_name}}  - Replaced with contact's last name
    {{full_name}}  - Replaced with first + last name
    {{email}}      - Replaced with contact's email address
  
  Click the merge tag code on the screen to insert it into
  your email body.

SENDING A CAMPAIGN:
  1. From the Campaigns list, click "Send" next to a draft
  2. Review the recipient count
  3. Choose "Send Now" or "Schedule for Later"
  4. If scheduling, pick a date and time
  5. Click "Queue Emails"
  
  This adds the emails to the Queue.
  Go to the Queue page and click "Process Queue Now" to send.

DUPLICATING A CAMPAIGN:
  Click "Copy" next to any campaign to create a duplicate draft.

------------------------------------------------------------
EMAIL QUEUE
------------------------------------------------------------

The queue holds emails waiting to be sent.

PROCESSING THE QUEUE:
  Click "Process Queue Now" to send the next batch of emails.
  The batch size is set by your administrator (default: 20 at once).

STATUSES:
  - Pending: Waiting to be sent
  - Sent: Successfully delivered to SMTP server
  - Failed: Could not send (see error column)
  - Skipped: Contact was unsubscribed or bounced

FAILED EMAILS:
  Emails are retried up to 3 times before being marked failed.
  Check the error message column to understand what went wrong.
  Common issues: wrong SMTP credentials, recipient email bounced.

AUTOMATIC PROCESSING:
  If your administrator has set up a cron job, emails will be
  processed automatically every few minutes.

------------------------------------------------------------
AUTOMATIONS
------------------------------------------------------------

Automations run a series of actions automatically when
something happens (the "trigger").

TRIGGERS - What starts an automation:
  - Contact Created: Fires when a new contact is added
  - Tag Added: Fires when a specific tag is added to a contact
  - Tag Removed: Fires when a specific tag is removed

STEP TYPES - What the automation does:
  - Send Email: Sends an email to the contact
  - Add Tag: Adds a tag to the contact
  - Remove Tag: Removes a tag from the contact
  - Wait: Pauses for a number of hours before the next step

CREATING AN AUTOMATION:
  1. Click "Automations" in the sidebar
  2. Click "New Automation"
  3. Give it a name
  4. Check "Enable this automation"
  5. Select a Trigger Type
  6. If the trigger is tag-based, select which tag
  7. Click "Add Step" to add actions
  8. Configure each step
  9. Click "Save Automation"

EXAMPLE - Welcome Email Automation:
  Trigger: Contact Created
  Step 1: Send Email (subject: "Welcome!", body: "Hi {{first_name}}, welcome!")
  Step 2: Wait 24 hours
  Step 3: Add Tag (tag: "Welcome Sent")

EXAMPLE - Tag-Based Drip:
  Trigger: Tag Added → "Interested"
  Step 1: Send Email (immediate intro email)
  Step 2: Wait 48 hours
  Step 3: Send Email (follow-up)
  Step 4: Wait 72 hours
  Step 5: Add Tag → "Drip Complete"
  Step 6: Remove Tag → "Interested"

RUNNING AUTOMATIONS:
  Automations queue up their steps when triggered. To actually
  execute them, click "Run Automations" on the Queue page,
  or wait for the cron job to run.

ACTIVATING/DEACTIVATING:
  On the Automations page, click "Activate" or "Deactivate"
  to toggle an automation on or off. Inactive automations
  will not fire when triggered.

------------------------------------------------------------
TROUBLESHOOTING
------------------------------------------------------------

"Emails not sending / SMTP error":
  - Go to SMTP Settings and click "Send Test Email"
  - Read the error message carefully
  - Double-check your SMTP credentials
  - For Gmail, use an App Password

"No contacts found for campaign":
  - Check your tag filter - if you selected tags, only contacts
    with those tags will receive the campaign
  - Check contacts are set to "Active" status

"Automation doesn't seem to fire":
  - Check it's set to Active on the Automations page
  - Click "Run Automations" on the Queue page
  - Verify the trigger condition is correct

"I imported contacts but they don't show up":
  - Refresh the Contacts page
  - Check your CSV has a header row with 'email' column name
  - Check the file is under 5MB

============================================================