# Workflow Automation

MailTrixy's workflow automation engine lets you build powerful, event-driven processes that run without manual intervention. Using a visual node-based builder, you can design workflows that trigger on specific events, evaluate conditions, and execute actions across your entire CRM and email system.

## Visual Node-Based Builder

The workflow builder provides an intuitive drag-and-drop canvas where you connect nodes to define your automation logic:

- Canvas: An infinite, pannable, and zoomable canvas where you place and connect workflow nodes. Use the mouse wheel to zoom and click-drag on empty space to pan.
- Node Palette: A sidebar lists all available node types grouped by category (Triggers, Conditions, Actions, Timing). Drag nodes from the palette onto the canvas.
- Connections: Draw connections between nodes by dragging from an output port to an input port. Connections define the execution flow.
- Node Configuration: Click any node to open its configuration panel on the right side. Each node type has specific settings (described below).
- Branching: Condition nodes have two output ports (True/False), enabling branching logic. Multiple branches can run in parallel.
- Validation: The builder validates your workflow before activation, checking for disconnected nodes, missing configurations, and logical errors.

## Trigger Types

Every workflow starts with a trigger node that defines when the workflow should execute:

### Email Triggers

- Email Received: Fires when an email is received in any connected inbox. Can be filtered by sender, subject, account, or keywords.
- Email Opened: Fires when a tracked email is opened by the recipient.
- Email Clicked: Fires when a link in a tracked email is clicked. Can be filtered to specific links.
- Email Bounced: Fires when a sent email bounces (hard or soft).
- Email Replied: Fires when a recipient replies to a sent email.

### Contact Triggers

- Contact Created: Fires when a new contact is added to the CRM (manually, via import, or auto-created from email).
- Contact Updated: Fires when a contact's field is modified. Can be filtered to specific fields.
- Tag Added: Fires when a specific tag is applied to a contact.
- List Subscription: Fires when a contact subscribes to a specific list.

### Deal Triggers

- Deal Created: Fires when a new deal is added to any pipeline.
- Deal Stage Changed: Fires when a deal moves to a different stage. Can be filtered to specific stages or pipelines.
- Deal Won/Lost: Fires when a deal is marked as won or lost.

### Other Triggers

- Webhook Trigger: Fires when an external system sends a POST request to the workflow's unique webhook URL. The request body is available as workflow data.
- Manual Trigger: Allows the workflow to be started manually from the UI or API. Useful for on-demand processes.
- Scheduled Trigger: Fires on a cron-like schedule (e.g., every day at 9 AM, every Monday, first of the month). Uses the workspace time zone.
- Form Submission: Fires when a MailTrixy web form is submitted.

### Real-World Examples

- Auto-assign support emails: When an email arrives at support@yourcompany.com containing "billing" in the subject, automatically assign it to the Billing team.
- Welcome new contacts: When a new contact is created, wait 5 minutes, then send a personalized welcome email using a template.
- Follow up on stale deals: When a deal has been in the "Proposal Sent" stage for 7 days with no activity, send a follow-up email and notify the sales rep.
- Escalate unanswered emails: When an email has been in the inbox for 4 hours with no reply, assign it to a manager and add an "urgent" tag.

## Condition Nodes (If/Else)

Condition nodes evaluate a logical expression and route execution to the True or False branch:

- Contact Field Conditions: Check any contact field value (e.g., "If contact.country equals United States", "If lead_score is greater than 50").
- Custom Field Conditions: Evaluate custom field values using comparison operators (equals, not equals, contains, greater than, less than, is empty, is not empty).
- Tag Conditions: Check if a contact has or does not have a specific tag.
- Email Engagement: Check if a contact opened or clicked a specific campaign email.
- Date Conditions: Compare dates (e.g., "If contact.created_at is within the last 7 days").
- Compound Conditions: Combine multiple conditions with AND/OR logic within a single condition node.

## Action Nodes

Action nodes perform operations when the workflow execution reaches them:

- Send Email: Send an email to the trigger contact using a template or custom content. Supports personalization variables. Can send from any connected email account.
- Add Tag: Apply one or more tags to the contact.
- Remove Tag: Remove specific tags from the contact.
- Update Contact: Modify any field on the contact record (e.g., set lead status to "Qualified").
- Add to List: Subscribe the contact to a specified list.
- Remove from List: Unsubscribe the contact from a specified list.
- Create Deal: Create a new deal in a specified pipeline and stage, linked to the contact.
- Move Deal: Move an associated deal to a different stage.
- Assign to Team Member: Assign the contact or deal to a specific team member or use round-robin assignment.
- Send Webhook: Make an HTTP POST/PUT/GET request to an external URL with customizable headers and JSON body. Useful for integrating with third-party services (Slack, CRMs, Zapier, etc.).
- Add Note: Add a note to the contact's activity timeline.
- Send Notification: Send an in-app or email notification to a team member.

## Wait and Delay Nodes

Control the timing of your workflow execution:

- Wait (Fixed Delay): Pause execution for a specified duration (minutes, hours, or days). For example, wait 3 days before sending a follow-up email.
- Wait Until (Date): Pause until a specific date/time or until a contact field date is reached (e.g., wait until the contact's renewal date).
- Wait for Event: Pause until a specific event occurs (e.g., wait until the contact opens an email or clicks a link). Includes a timeout (e.g., wait for open event for up to 5 days; if no open, continue down the False branch).

> Tip: Wait nodes use the Laravel queue delay mechanism. The workflow execution state is persisted to the database, so waits survive server restarts and queue worker recycling.

## Execution Logs

Every workflow execution is logged for debugging and auditing:

- Execution List: View all executions for a workflow with status (completed, running, failed, timed out), start time, duration, and trigger data.
- Step-by-Step Log: Click an execution to see the detailed step log. Each node execution is recorded with its input data, output data, and result (success/failure).
- Error Details: Failed nodes display the error message and stack trace. Common errors include invalid email addresses, webhook timeouts, and missing template variables.
- Replay: Re-run a failed execution from the point of failure after fixing the issue. The workflow resumes from the failed node with the original trigger data.
- Log Retention: Execution logs are retained for 90 days by default (configurable). Older logs are automatically purged.

## 50 Pre-Built Workflow Templates

MailTrixy includes 50 ready-to-use workflow templates covering common automation scenarios. Templates can be installed with one click and customized to your needs:

- Welcome Series: Send a 5-email onboarding sequence when a contact joins a list.
- Lead Qualification: Score leads based on email engagement and route high-scoring leads to sales.
- Abandoned Cart Follow-Up: Send reminder emails when a deal goes stale in the early pipeline stages.
- Birthday Email: Automatically send a personalized birthday email using the contact's date of birth field.
- Re-engagement Campaign: Identify inactive contacts (no opens in 60 days) and send a re-engagement sequence.
- Deal Won Notification: Notify the team via Slack webhook and send a thank-you email when a deal is closed won.
- New Lead Assignment: Round-robin assign new contacts to sales reps based on availability.
- Feedback Request: Send a satisfaction survey 7 days after a deal is closed.
- Webinar Follow-Up: Tag webinar attendees and send follow-up content based on attendance status.
- Subscription Renewal Reminder: Send reminders at 30, 14, and 3 days before subscription expiry.

And 40 more templates covering SaaS onboarding, e-commerce sequences, agency client management, event promotion, internal notifications, data hygiene routines, and more.

## Cycle Detection and Timeout Protection

MailTrixy includes safeguards to prevent runaway workflows:

- Cycle Detection: The workflow builder analyzes the node graph and detects circular references (loops). Workflows with cycles cannot be activated. If you need looping behavior, use the scheduled trigger to restart the workflow at intervals.
- Maximum Node Limit: A single workflow can have up to 100 nodes. This prevents excessively complex workflows that are difficult to maintain and debug.
- Execution Timeout: Each workflow execution has a maximum lifetime of 30 days (configurable). If a workflow has not completed within this period (e.g., a wait node with an unreachable condition), it is automatically terminated and marked as "timed out".
- Rate Limiting: Workflows are rate-limited to prevent email flooding. A workflow can send a maximum of 100 emails per contact per 24-hour period. This limit is configurable per workspace.
- Duplicate Prevention: A contact can only have one active execution of the same workflow at a time. If the trigger fires again while the contact is already in the workflow, the new execution is skipped (or optionally queued).