Email-to-Ticket Configuration Guide

Time to complete: 30 minutes

Difficulty: Intermediate

Prerequisites: Admin access, email account credentials

Overview

Valethon automatically converts incoming emails into support tickets. This guide covers configuring email sources using OAuth2 (Gmail, Microsoft 365) or traditional SMTP/IMAP.

Email Architecture

Valethon supports two email configurations:

You can use both: company-specific mailboxes are processed first, then the system mailbox handles everything else.

Option 1: Gmail (OAuth2 + Gmail API)

Gmail integration uses OAuth2 for secure, password-free authentication.

Step 1: Create Google Cloud Project

• Go to Google Cloud Console
• Create a new project (e.g., "Valethon Email Integration")
• Enable the Gmail API:
• APIs & Services → Library
• Search "Gmail API" → Enable

Step 2: Configure OAuth Consent Screen

• APIs & Services → OAuth consent screen
• Choose Internal (if using Google Workspace) or External
• Fill in required fields:
• App name: "Valethon ServiceOS"
• Support email: Your admin email
• Authorized domains: Your Valethon domain
• Add scopes:
• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.modify
• Save and continue

Step 3: Create OAuth Credentials

• APIs & Services → Credentials
• Create Credentials → OAuth client ID
• Application type: Web application
• Name: "Valethon Email"
• Authorized redirect URIs:

   https://your-instance.valethon.com/admin/oauth/google/callback.php

• Download the JSON credentials file

Step 4: Configure in Valethon

• Navigate to Settings → Email Configuration
• Click Add Email Source
• Select Gmail (OAuth2)
• Enter:
• Client ID (from Google)
• Client Secret (from Google)
• Redirect URI (must match Google exactly)
• Click Authorize
• Complete Google sign-in in popup window
• Grant permissions when prompted

Step 5: Test the Connection

• Send a test email to your support address
• Wait 5 minutes (or click "Process Now")
• Check Tickets for the new ticket

Option 2: Microsoft 365 (OAuth2 + Graph API)

Microsoft 365 integration uses the Microsoft Graph API.

Step 1: Register Azure AD Application

• Go to Azure Portal
• Navigate to Azure Active Directory → App registrations
• Click New registration:
• Name: "Valethon Email Integration"
• Supported account types: Accounts in this org only
• Redirect URI: Web, https://your-instance.valethon.com/admin/oauth/microsoft/callback.php
• Note the Application (client) ID and Directory (tenant) ID

Step 2: Add API Permissions

• API permissions → Add a permission
• Microsoft Graph → Delegated permissions
• Add these permissions:
• Mail.Read
• Mail.ReadWrite
• User.Read
• Click Grant admin consent (requires admin)

Step 3: Create Client Secret

• Certificates & secrets → New client secret
• Description: "Valethon Email"
• Expiration: Choose appropriate duration
• Copy the secret value immediately (shown only once)

Step 4: Configure in Valethon

• Navigate to Settings → Email Configuration
• Click Add Email Source
• Select Microsoft 365 (OAuth2)
• Enter:
• Tenant ID
• Client ID
• Client Secret
• Redirect URI
• Click Authorize
• Complete Microsoft sign-in
• Grant permissions when prompted

Option 3: IMAP/SMTP (Traditional)

For email providers that don't support OAuth2, use traditional IMAP.

Supported Providers

Configuration Steps

• Navigate to Settings → Email Configuration
• Click Add Email Source
• Select IMAP/SMTP
• Enter:
• IMAP Server address
• Port (usually 993)
• Email address
• Password (or app-specific password)
• Security: SSL/TLS
• Click Test Connection
• If successful, click Save

App-Specific Passwords

Many providers require app-specific passwords:

• iCloud: Apple ID → Security → App-Specific Passwords
• Yahoo/AOL: Account Security → Generate app password
• Zoho: Security → App Passwords

Domain-Based Routing

When using a system mailbox, Valethon routes tickets by sender domain.

Configure Domain Mapping

• Navigate to Customers → [Company] → Settings
• Click Email Domains
• Add domains associated with this company:
• acme.com
• acme-corp.com
• Save

How Routing Works

• Email arrives from john@acme.com
• Valethon checks domain mappings
• Finds acme.com → Acme Corporation
• Creates ticket for Acme Corporation
• Matches sender to contact if email exists

Unmapped Domains

Emails from unmapped domains:

• Create tickets assigned to your default company
• Or can be configured to create new leads (CRM integration)

Email Processing Options

Processing Schedule

Configure in Settings → Email Configuration → Schedule.

Ticket Creation Rules

Thread Matching

Valethon matches replies to existing tickets using:

• Subject line ticket number: Re: [Ticket #1234] Your request
• Email headers (In-Reply-To, References)
• Message-ID tracking

Matched replies become ticket notes, not new tickets.

Troubleshooting

Emails Not Converting to Tickets

• Check Settings → Email Configuration → Connection Status
• Review error logs: Admin → System → Error Log
• Verify OAuth tokens haven't expired
• Test with "Process Now" button

OAuth Token Expired

• Click Re-authorize next to the email source
• Complete sign-in again
• Tokens refresh automatically (30-60 days)

Duplicate Tickets

Usually caused by:

• Email forwarding creating duplicates
• Multiple mailboxes processing same email
• Thread matching failing

Solution: Configure email rules to avoid duplicates, check thread matching settings.

Attachments Missing

• Verify attachment limit (default 25MB)
• Check allowed file types in settings
• Review storage space allocation

Best Practices

Security

• Use OAuth2 when available (no passwords stored)
• Enable MFA on email accounts
• Review email permissions quarterly
• Rotate app-specific passwords annually

Organization

• Use company-specific mailboxes for VIP customers
• Configure domain mappings for all customer domains
• Set appropriate default priorities by job type

Monitoring

• Check "Last Processed" timestamps daily
• Set up alerts for processing failures
• Review unmatched emails weekly

What's Next?

Last updated: January 2026