Email Piping Setup Guide

Email piping allows your HelpDesk system to automatically create tickets from incoming emails. This feature enables customers to send support requests via email, which are automatically converted into tickets in your system.

📋 Table of Contents

• Overview
• Requirements
• cPanel Setup
• VPS/Server Setup
• Gmail Integration
• Testing Email Piping
• Troubleshooting
• Best Practices

---

Overview

Email piping provides the following benefits:

• ✅ Automatic Ticket Creation - Emails become tickets instantly
• ✅ Reply-to-Email Support - Responses create ticket replies
• ✅ Thread Management - Maintains email conversation threads
• ✅ Attachment Support - Email attachments become ticket attachments
• ✅ Customer Recognition - Automatically identifies existing customers
• ✅ Department Routing - Routes emails to appropriate departments

How It Works

Customer Email → Email Server → Pipe Script → HelpDesk API → New Ticket

1. Customer sends email to your support address
2. Email server receives the email
3. Pipe script processes the email content
4. HelpDesk API creates a new ticket
5. Customer receives confirmation and ticket number

---

Requirements

Server Requirements

• PHP 8.2+ with cURL extension
• Email server with forwarding capabilities
• Web server access for script placement
• HelpDesk system deployed and accessible

HelpDesk Configuration

1. API Endpoint Active

   • Ensure /api/email-handler is accessible
   • Verify API authentication is working

2. Environment Variables

   EMAIL_WEBHOOK_TOKEN=your-secure-token-here

3. Email Settings

   • Configure SMTP settings in admin panel
   • Test email sending functionality

---

cPanel Setup

Step 1: Create the Pipe Script

1. Create Directory

   • Log into cPanel File Manager
   • Create a new directory outside public_html (recommended: email_pipe)
   • This keeps the script secure and accessible

2. Create Pipe Script

   • Create a new file named pipe.php in the email_pipe directory
   • Copy the following script:

#!/usr/bin/php -q
<?php

// Configuration
$app_uri = "https://yourdomain.com/api/email-handler";
$pipe_token = 'YOUR_PIPE_TOKEN_HERE';

// Read email from stdin
$stdin = fopen("php://stdin", "r");
$email = '';
while (!feof($stdin)) {
    $email .= fread($stdin, 1024);
}
fclose($stdin);

// Parse email headers
preg_match('/^From:\s*(.+)/mi', $email, $fromMatch);
$fromLine = trim($fromMatch[1] ?? '');
$from_email = $fromLine;
$from_name = '';

// Extract name and email from "Name <email@domain.com>" format
if (preg_match('/^(.*)<(.+@.+)>$/', $fromLine, $matches)) {
    $from_name = trim($matches[1], '" ');
    $from_email = trim($matches[2]);
}

// Parse other email headers
preg_match('/^Subject:\s*(.+)/mi', $email, $subjectMatch);
preg_match('/^Message-ID:\s*(.+)/mi', $email, $messageIdMatch);
preg_match('/^In-Reply-To:\s*(.+)/mi', $email, $inReplyToMatch);

// Extract email body
$body = preg_split("/\r?\n\r?\n/", $email, 2)[1] ?? '';

// Prepare payload for API
$payload = [
    'from'         => $from_email,
    'from_name'    => $from_name,
    'subject'      => trim($subjectMatch[1] ?? '(no subject)'),
    'body'         => trim($body),
    'message_id'   => trim($messageIdMatch[1] ?? ''),
    'in_reply_to'  => trim($inReplyToMatch[1] ?? ''),
    'date'         => date('c'),
];

// Send to HelpDesk API
$ch = curl_init($app_uri);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Webhook-Token: ' . $pipe_token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // For development only

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Log response for debugging (optional)
if ($httpCode !== 200) {
    error_log("Email pipe error: HTTP $httpCode - $response");
}

?>

3. Update Configuration
   • Replace https://yourdomain.com with your actual domain
   • Replace YOUR_PIPE_TOKEN_HERE with your actual webhook token
   • Save the file

Step 2: Set File Permissions

1. Using cPanel File Manager

   • Right-click on pipe.php
   • Select "Change Permissions"
   • Set permissions to 755:
     • ✅ Owner: Read, Write, Execute
     • ✅ Group: Read, Execute
     • ✅ World: Read, Execute

2. Using Terminal (if available)

   chmod 755 /home/yourusername/email_pipe/pipe.php

Step 3: Configure Email Forwarder

1. Access Email Forwarders

   • In cPanel, go to "Email" → "Forwarders"
   • Click "Add Forwarder"

2. Create Forwarder

   ┌─────────────────────────────────────────────────────────────┐
   │ Add Forwarder                                               │
   ├─────────────────────────────────────────────────────────────┤
   │ Address to Forward: *                                       │
   │ ┌─────────────────────────────────────────────────────────┐ │
   │ │ support@yourdomain.com                                 │ │
   │ └─────────────────────────────────────────────────────────┘ │
   │                                                             │
   │ Destination:                                                │
   │ ○ Forward to Email Address                                 │
   │ ● Pipe to a Program                                         │
   │                                                             │
   │ Program: *                                                  │
   │ ┌─────────────────────────────────────────────────────────┐ │
   │ │ email_pipe/pipe.php                                     │ │
   │ └─────────────────────────────────────────────────────────┘ │
   │                                                             │
   │ [Add Forwarder] [Cancel]                                   │
   └─────────────────────────────────────────────────────────────┘

3. Important Notes

   • Use relative path: email_pipe/pipe.php
   • Do NOT use leading slash /
   • Path is relative to your home directory

---

Testing Email Piping

Step 1: Basic Functionality Test

1. Send Test Email

   # Using command line
   echo "Test email body" | mail -s "Test Subject" support@yourdomain.com
   
   # Or send from any email client

2. Check Results

   • Log into HelpDesk admin panel
   • Go to Tickets section
   • Look for new ticket created from your test email

Step 2: Advanced Testing

1. Test with Attachments

   • Send email with file attachments
   • Verify attachments appear in the ticket

2. Test Reply Functionality

   • Reply to the auto-generated ticket email
   • Check if reply appears as ticket comment

3. Test Thread Management

   • Send multiple emails with same subject
   • Verify they create a conversation thread

---

Troubleshooting

Common Issues

Email Not Creating Tickets

Symptoms: Emails sent to support address don't create tickets

Solutions:

1. Check Script Permissions

   ls -la /path/to/pipe.php
   # Should show: -rwxr-xr-x

2. Verify Script Path

   • Ensure forwarder uses correct relative path
   • Test script manually: echo "test" | /path/to/pipe.php

3. Check API Endpoint

   • Test API directly: curl -X POST https://yourdomain.com/api/email-handler
   • Verify webhook token is correct

4. Review Error Logs

   • Check PHP error logs
   • Check mail server logs
   • Check HelpDesk application logs

Script Execution Errors

Symptoms: Script fails to execute or returns errors

Solutions:

1. Check PHP Path

   which php
   # Update shebang line if needed: #!/usr/bin/php -q

2. Test Script Manually

   echo "From: test@example.com\nSubject: Test\n\nTest body" | php /path/to/pipe.php

3. Check Dependencies

   • Ensure cURL extension is installed
   • Verify PHP version compatibility

---

Best Practices

Security

1. Secure Script Location

   • Place scripts outside web root
   • Use proper file permissions (755)
   • Regular security updates

2. Token Security

   • Use strong, unique webhook tokens
   • Rotate tokens regularly
   • Monitor for unauthorized access

3. Input Validation

   • Validate email content before processing
   • Sanitize user input
   • Implement rate limiting

Monitoring

1. Log Monitoring

   • Set up log monitoring alerts
   • Track failed email processing
   • Monitor API response times

2. Health Checks

   • Regular script functionality tests
   • API endpoint monitoring
   • Email delivery verification

---

📞 Need Help?

If you encounter issues with email piping:

1. Check Documentation: Review this guide for solutions
2. Contact Support: Get help from our support team
3. Community Forum: Ask questions in our user community

---

Last updated: January 2025