​
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 "[email protected]" \
  --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
# [email protected] 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

FlagDescription
--route-idUse existing route instead of creating temporary one
--recipientRecipient pattern for temporary route (e.g., *@domain.com)
--forward-toLocal endpoint to forward events to
--skip-verifySkip SSL certificate verification for local endpoints when forwarding events
--slim-outputSlim 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 "[email protected]" \
  --forward-to http://localhost:3000/tickets/create

​
Email-to-Task Integration

# Convert emails to tasks
ahasend routes listen --recipient "[email protected]" \
  --forward-to http://localhost:3000/api/tasks/from-email

​
Best Practices

  1. Use Temporary Routes for Testing: Create temporary routes with wildcards during development
  2. Verify Signatures: Always validate webhook signatures in production
  3. Handle WebSocket Disconnects: Implement reconnection logic for production use
  4. Test with Trigger Command: Use trigger to test without sending real emails
  5. 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

​
Next Steps