Route Testing

Test and debug inbound email routing locally using the AhaSend CLI’s WebSocket-based route listener.

Overview

The CLI provides tools for:

Listening to inbound email events in real-time using WebSocket connection
Using existing routes or creating temporary routes with recipient patterns
Forwarding events to local endpoints for development
Displaying events in full or slim output format
Handling disconnections with buffered event replay
Triggering test route events

Route Listener

Basic Usage

# Listen with existing route
ahasend routes listen --route-id abcd1234-5678-90ef-abcd-1234567890ab

# Listen with recipient pattern (backend creates temporary route)
ahasend routes listen --recipient "*@example.com"

# Listen for specific subdomain patterns
ahasend routes listen --recipient "support-*@example.com"

# Slim output (minimal event display)
ahasend routes listen --route-id abc123 --slim-output

Attachment data is not sent over WebSocket for performance reasons. Only email metadata and content are transmitted.
The command generates a webhook secret for signing forwarded events using the standard-webhooks specification.

Event Type

message.routing - Triggered when an inbound email matches a route

Event Forwarding

Forward to Local Server

# Forward events to local endpoint
ahasend routes listen \
  --recipient "support-*@example.com" \
  --forward-to http://localhost:3000/webhook

# Forward with existing route
ahasend routes listen \
  --route-id abcd1234-5678-90ef-abcd-1234567890ab \
  --forward-to http://localhost:3000/webhook

# Skip SSL verification for self-signed certificates
ahasend routes listen \
  --route-id abcd1234-5678-90ef-abcd-1234567890ab \
  --forward-to https://localhost:8443/webhook \
  --skip-verify

Event Headers

Forwarded requests include standard webhook headers:

webhook-id - Unique message identifier
webhook-timestamp - Unix timestamp
webhook-signature - HMAC signature for verification

Triggering Test Events

Development Testing

# Trigger a message.routing event for testing
ahasend routes trigger abcd1234-5678-90ef-abcd-1234567890ab

Finding Route IDs

# List all routes to find IDs
ahasend routes list

Integration Testing

Development Workflow

# 1. Create a route for testing
ahasend routes create \
  --match-recipient "test@example.com" \
  --forward-to "https://app.example.com/webhook" \
  --description "Test inbound route"

# 2. Start listening for events
ahasend routes listen --route-id <route-id> \
  --forward-to http://localhost:3000/webhook

# 3. Trigger test event (in another terminal)
ahasend routes trigger <route-id>

# 4. Send test email to the route address
# test@example.com will trigger the route

Output Formats

Standard Output

# Full event details (default)
ahasend routes listen --route-id abc123

Slim Output

# Minimal console display
ahasend routes listen --route-id abc123 --slim-output

Common Flags

Flag	Description
`--route-id`	Use existing route instead of creating temporary one
`--recipient`	Recipient pattern for temporary route (e.g., *@domain.com)
`--forward-to`	Local endpoint to forward events to
`--skip-verify`	Skip SSL certificate verification for local endpoints when forwarding events
`--slim-output`	Slim down the payload for printing to the console

Use Cases

Testing Inbound Email Processing

# Set up listener for all emails to your domain
ahasend routes listen --recipient "*@yourdomain.com" \
  --forward-to http://localhost:3000/inbound

Support Ticket System

# Route support emails to local handler
ahasend routes listen --recipient "support@example.com" \
  --forward-to http://localhost:3000/tickets/create

Email-to-Task Integration

# Convert emails to tasks
ahasend routes listen --recipient "tasks@example.com" \
  --forward-to http://localhost:3000/api/tasks/from-email

Best Practices

Use Temporary Routes for Testing: Create temporary routes with wildcards during development
Verify Signatures: Always validate webhook signatures in production
Handle WebSocket Disconnects: Implement reconnection logic for production use
Test with Trigger Command: Use trigger to test without sending real emails
Use Slim Output for Monitoring: Reduce console clutter when monitoring events

Troubleshooting

WebSocket Connection Failed: Check network connectivity and firewall settings Events Not Received: Verify the route pattern matches the recipient address Signature Verification Failed: The command automatically generates a webhook secret using the standard-webhooks specification Route Not Found: Check route ID with ahasend routes list

Getting Started

Commands

Features

Route Testing

Route Testing

Overview

Route Listener

Basic Usage

Event Type

Event Forwarding

Forward to Local Server

Event Headers

Triggering Test Events

Development Testing

Finding Route IDs

Integration Testing

Development Workflow

Output Formats

Standard Output

Slim Output

Common Flags

Use Cases

Testing Inbound Email Processing

Support Ticket System

Email-to-Task Integration

Best Practices

Troubleshooting

Next Steps

​Route Testing

​Overview

​Route Listener

​Basic Usage

​Event Type

​Event Forwarding

​Forward to Local Server

​Event Headers

​Triggering Test Events

​Development Testing

​Finding Route IDs

​Integration Testing

​Development Workflow

​Output Formats

​Standard Output

​Slim Output

​Common Flags

​Use Cases

​Testing Inbound Email Processing

​Support Ticket System

​Email-to-Task Integration

​Best Practices

​Troubleshooting

​Next Steps

Route Testing

Overview

Route Listener

Basic Usage

Event Type

Event Forwarding

Forward to Local Server

Event Headers

Triggering Test Events

Development Testing

Finding Route IDs

Integration Testing

Development Workflow

Output Formats

Standard Output

Slim Output

Common Flags

Use Cases

Testing Inbound Email Processing

Support Ticket System

Email-to-Task Integration

Best Practices

Troubleshooting

Next Steps