Email Piping Setup Guide · HelpDesk Pro – AI Helpdesk & Customer Support Software with Live Chat Documentation

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.

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

Customer sends email to your support address
Email server receives the email
Pipe script processes the email content
HelpDesk API creates a new ticket
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

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

Environment Variables

EMAIL_WEBHOOK_TOKEN=your-secure-token-here

Email Settings
- Configure SMTP settings in admin panel
- Test email sending functionality

cPanel Setup

Step 1: Create the Pipe Script

Create Directory
- Log into cPanel File Manager
- Create a new directory outside public_html (recommended: email_pipe)
- This keeps the script secure and accessible
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");
}

?>

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

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

Using Terminal (if available)

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

Step 3: Configure Email Forwarder

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

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]                                   │
└─────────────────────────────────────────────────────────────┘

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

Send Test Email

# Using command line
echo "Test email body" | mail -s "Test Subject" support@yourdomain.com

# Or send from any email client

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

Step 2: Advanced Testing

Test with Attachments
- Send email with file attachments
- Verify attachments appear in the ticket
Test Reply Functionality
- Reply to the auto-generated ticket email
- Check if reply appears as ticket comment
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:

Check Script Permissions

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

Verify Script Path
- Ensure forwarder uses correct relative path
- Test script manually: echo "test" | /path/to/pipe.php
Check API Endpoint
- Test API directly: curl -X POST https://yourdomain.com/api/email-handler
- Verify webhook token is correct
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:

Check PHP Path

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

Test Script Manually

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

Check Dependencies
- Ensure cURL extension is installed
- Verify PHP version compatibility

Best Practices

Security

Secure Script Location
- Place scripts outside web root
- Use proper file permissions (755)
- Regular security updates
Token Security
- Use strong, unique webhook tokens
- Rotate tokens regularly
- Monitor for unauthorized access
Input Validation
- Validate email content before processing
- Sanitize user input
- Implement rate limiting

Monitoring

Log Monitoring
- Set up log monitoring alerts
- Track failed email processing
- Monitor API response times
Health Checks
- Regular script functionality tests
- API endpoint monitoring
- Email delivery verification

📞 Need Help?

If you encounter issues with email piping:

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

Last updated: January 2025