Test Inbound Email Routes Locally with the CLI

Stream inbound email events to localhost with ahasend routes listen, forward them to your app with signed headers, and trigger test events.

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

Before running the examples, log in with a full API key, use your verified sender domain, and replace YOUR_RESOURCE_ID with a resource UUID from your test account. Create any named template, recipient, attachment, or JSON files first. Shell examples use Bash; examples that read JSON with jq need jq installed. Sends use sandbox mode.

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

Temporary routes need a domain in your account with its AhaSend MX records configured. An existing route must be enabled to emit events. For a disabled test route, start its listener, then run ahasend routes update YOUR_RESOURCE_ID --enabled in another terminal; disable it again before stopping the listener. Temporary listeners are enabled automatically.

# Listen with existing route
ahasend routes listen --route-id YOUR_RESOURCE_ID

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

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

# Slim output (minimal event display)
ahasend routes listen --route-id YOUR_RESOURCE_ID --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 headers and format, with the full secret as raw UTF-8 bytes.

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 YOUR_RESOURCE_ID \
  --forward-to http://localhost:3000/webhook

# Skip SSL verification for self-signed certificates
ahasend routes listen \
  --route-id YOUR_RESOURCE_ID \
  --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 YOUR_RESOURCE_ID

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 --interactive=false \
  --recipient "[e-mail]" \
  --url "https://app.example.com/webhook" \
  --name "Test inbound route"

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

# 3. Trigger test event (in another terminal)
ahasend routes trigger YOUR_RESOURCE_ID

# 4. Send test email to the route address
# [e-mail] will trigger the route

Output Formats

Standard Output

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

Slim Output

# Minimal console display
ahasend routes listen --route-id YOUR_RESOURCE_ID --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 "[e-mail]" \
  --forward-to http://localhost:3000/tickets/create

Email-to-Task Integration

# Convert emails to tasks
ahasend routes listen --recipient "[e-mail]" \
  --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. Use listeners for development: Configure a real route URL for production
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 listener prints its signing secret when it starts. Store that secret in your local handler’s configuration; use the full string as the raw UTF-8 HMAC key. Do not base64-decode it. See signature verification. The command automatically generates a webhook secret using the Standard Webhooks headers and format, with the full secret as raw UTF-8 bytes

Route Not Found: Check route ID with ahasend routes list

Next Steps

• Learn about routes
• Configure webhooks

Related Guides

• Install the CLI, CLI authentication, Inbound routing setup.
• Route payload, Route CLI, Signature verification.
• Retry policy, CLI configuration and output, API authentication.
• Permission scopes, Domain setup, Sandbox behavior.