> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Route Testing

> Test inbound email routing locally with the CLI

# 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

```bash theme={null}
# 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
```

<Note>
  * 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.
</Note>

### Event Type

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

## Event Forwarding

### Forward to Local Server

```bash theme={null}
# 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

```bash theme={null}
# Trigger a message.routing event for testing
ahasend routes trigger abcd1234-5678-90ef-abcd-1234567890ab
```

### Finding Route IDs

```bash theme={null}
# List all routes to find IDs
ahasend routes list
```

## Integration Testing

### Development Workflow

```bash theme={null}
# 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

```bash theme={null}
# Full event details (default)
ahasend routes listen --route-id abc123
```

### Slim Output

```bash theme={null}
# 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

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

### Support Ticket System

```bash theme={null}
# Route support emails to local handler
ahasend routes listen --recipient "support@example.com" \
  --forward-to http://localhost:3000/tickets/create
```

### Email-to-Task Integration

```bash theme={null}
# Convert emails to tasks
ahasend routes listen --recipient "tasks@example.com" \
  --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

* [Learn about routes](/cli/commands/routes)
* [Configure webhooks](/cli/commands/webhooks)