> ## 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. > ## Agent Instructions > AhaSend stores all message data in the EU. See /facts. > The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication. > Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp. > For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes. # ahasend routes: Manage Inbound Email Routes > Create and manage AhaSend inbound email routes from the CLI: match recipients, POST parsed emails to your webhook, and test locally with routes listen. AhaSend CLI `routes` commands let you manage inbound email routes, and forward and trigger their events; this page lists their arguments and flags. For the complete local testing workflow, use the [route testing guide](https://ahasend.com/docs/cli/route-testing.md). For dashboard setup, see [the routes guide](https://ahasend.com/docs/integrations/routing.md). Before running the examples, [log in](https://ahasend.com/docs/cli/authentication.md) with an API key that has the read, write and delete [route scopes](https://ahasend.com/docs/api-reference/scopes.md#email-routing) for all domains, and `messages:read` for the domain of the route's recipient, which `routes listen` and `routes trigger` need. Replace `example.com` in the recipients with a receiving domain: a domain in your account whose MX record points to AhaSend. Replace `YOUR_RESOURCE_ID` with the ID of one of your routes. ## Overview ```text theme={null} ahasend routes [subcommand] [flags] ``` Available subcommands: * `list` - List inbound email routes * `create` - Create an inbound email route * `get` - Get an inbound email route * `update` - Update an inbound email route * `delete` - Delete an inbound email route * `listen` - Listen for inbound email events in real-time * `trigger` - Trigger route events for testing `routes get`, `routes update`, `routes delete` and `routes trigger` take the route ID as their positional argument. A route ID that is not a UUID fails with exit code 4 before any request. Find IDs with `ahasend routes list`. A route receives email only when its domain's MX record points to AhaSend. The DNS records that `ahasend domains create` prints include that MX record, marked optional; see [domains](https://ahasend.com/docs/cli/commands/domains.md#create-domain). ## Recipient Patterns `--recipient`, on `create`, `update` and `listen`, takes the form `local@domain`. The domain must be one of your domains. The local part cannot be empty, and may be `*` or hold `*` wildcards: * `support@example.com` - one address * `*@example.com` - every address of the domain * `support-*@example.com` - every address that starts with `support-` A value of another form, such as `support@*`, fails with exit code 4 before any request. The API checks that the domain is one of yours. A route's recipient cannot be cleared. ## List Routes ```bash theme={null} # List all routes ahasend routes list # List up to 10 routes ahasend routes list --limit 10 # List the routes of one recipient domain ahasend routes list --domain example.com # Show only the enabled routes of the page ahasend routes list --enabled # Show only the disabled routes of the page ahasend routes list --enabled=false # JSON output ahasend routes list --output json ``` * `--domain` filters by recipient domain. An API key scoped to domains requires it. * `--enabled` filters the page that the API returned, so a page can hold fewer than `--limit` routes. It cannot be used with `--output json`, which prints the API's response unchanged; filter the routes' `enabled` field instead. * Pages work as [Lists and Pagination](https://ahasend.com/docs/cli/configuration.md#lists-and-pagination) describes. ## Create Route ```bash theme={null} # Create a route for one address ahasend routes create \ --name "Support route" \ --url https://api.example.com/inbound/support \ --recipient "support@example.com" # Route every address of a domain, with attachments ahasend routes create \ --name "Help desk" \ --url https://api.example.com/support \ --recipient "*@example.com" \ --include-attachments # Route with processing options, created disabled ahasend routes create \ --name "Sales inquiries" \ --url https://api.example.com/sales \ --recipient "sales-*@example.com" \ --include-headers \ --group-by-message-id \ --strip-replies \ --enabled=false ``` * `--name`, `--url` and `--recipient` are required. When one is missing and stdin is a terminal, the command asks for it. With `--non-interactive`, or when stdin is not a terminal, a missing value fails with exit code 4. * A route is enabled unless you set `--enabled=false`. The processing options are off unless you set their flags. * `--url` must be an HTTP or HTTPS URL with a host name and no user name or password. Use HTTPS in production: a plain HTTP URL for a host other than `localhost` or a loopback address prints a warning on stderr. The output shows the route's signing secret once, in every output format. Save it to [verify the signatures](https://ahasend.com/docs/api-reference/webhooks/security.md) of the emails the route posts; `routes get` does not show it. ## Get Route Show a route's name, URL, status, recipient, processing options, timestamps and call counters. The output has no secret: the API returns it only when you create the route. ```bash theme={null} ahasend routes get YOUR_RESOURCE_ID # Save the route's configuration as JSON ahasend routes get YOUR_RESOURCE_ID --output json > route-backup.json ``` ## Update Route Only the flags you set are sent; other settings stay as they are. Give at least one flag. Each on/off option turns off with `=false`. ```bash theme={null} # Change the name ahasend routes update YOUR_RESOURCE_ID --name "New route name" # Change the webhook URL ahasend routes update YOUR_RESOURCE_ID --url https://api.example.com/new-webhook # Enable or disable the route ahasend routes update YOUR_RESOURCE_ID --enabled ahasend routes update YOUR_RESOURCE_ID --enabled=false # Change the recipient pattern ahasend routes update YOUR_RESOURCE_ID --recipient "support-*@example.com" # Turn processing options on ahasend routes update YOUR_RESOURCE_ID \ --include-attachments \ --include-headers \ --group-by-message-id # Turn processing options off ahasend routes update YOUR_RESOURCE_ID \ --include-attachments=false \ --strip-replies=false ``` ## Delete Route ```bash theme={null} # Delete with a confirmation prompt ahasend routes delete YOUR_RESOURCE_ID # Skip the confirmation prompt ahasend routes delete YOUR_RESOURCE_ID --force ``` The command asks for confirmation first, as [Prompts](https://ahasend.com/docs/cli/configuration.md#prompts) describes; `--force` (`-f`) skips it. > [!WARNING] > > Deleting a route is irreversible. To keep a route for later, disable it instead: `ahasend routes update YOUR_RESOURCE_ID --enabled=false`. ## Listen for Inbound Email `routes listen` streams inbound email events (`message.routing`) to your terminal over a WebSocket connection, and can forward each event to a local endpoint. It prints events as text, whatever `--output` says, and runs until you press Ctrl+C or the connection closes. Give exactly one of `--route-id` and `--recipient`. ```bash theme={null} # Listen through an existing route ahasend routes listen --route-id YOUR_RESOURCE_ID # Listen through a temporary route for a recipient pattern ahasend routes listen --recipient "*@example.com" # Forward events to a local server ahasend routes listen --recipient "support-*@example.com" \ --forward-to http://localhost:3000/webhook ``` The API key needs the `routes:write:all` scope, and `messages:read` for the domain of the route's recipient. With `--recipient`, the API creates a temporary route that stays after the command ends. Forwarded events are signed with a forwarding secret that the command prints when it connects. The [route testing guide](https://ahasend.com/docs/cli/route-testing.md) covers temporary routes, forwarding, signatures and exit codes. ## Trigger Test Events `routes trigger` asks the API to send a test `message.routing` event to a route, so you can test your endpoint without sending real email. The API key needs `messages:read` for the domain of the route's recipient (`messages:read:all`, or `messages:read:{example.com}`); route scopes do not grant it. ```bash theme={null} ahasend routes trigger YOUR_RESOURCE_ID ``` The output is the API's message. A disabled route gets no event: the API answers that it is queued, and then drops it. Enable the route first with `ahasend routes update YOUR_RESOURCE_ID --enabled`. ## Command Flags These flags come from the CLI's `--help`. All commands also accept the [global flags](https://ahasend.com/docs/cli/configuration.md#global-flags). ### `routes create` | Flag | Description and default | | - | - | | `--enabled` | Enable the route (the API enables it when omitted) (default true) | | `--group-by-message-id` | Group related emails by message ID (conversation threading) | | `--idempotency-key string` | Idempotency key for safe retries (generated when omitted) | | `--include-attachments` | Include email attachments in webhook payload | | `--include-headers` | Include email headers in webhook payload | | `--name string` | Route name (required) | | `--non-interactive` | Never prompt; fail when a required flag is missing | | `--recipient string` | Recipient filter, `local@domain`, such as `support@example.com` or `*@example.com` (required) | | `--strip-replies` | Strip reply content from emails | | `--url string` | Webhook URL for processing emails (required) | ### `routes delete` | Flag | Description and default | | - | - | | `-f`, `--force` | Skip confirmation prompt | ### `routes get` This command has no command-specific flags. See [global flags](https://ahasend.com/docs/cli/configuration.md#global-flags). ### `routes list` | Flag | Description and default | | - | - | | `--after string` | Return the page after this cursor | | `--before string` | Return the page before this cursor | | `--domain string` | Filter by recipient domain (required with a domain-scoped API key) | | `--enabled` | Show only enabled (`--enabled`) or disabled (`--enabled=false`) routes of the page (not with `--output json`) | | `--limit int32` | Maximum number of items to return (0-100; 0 uses the API default) | ### `routes listen` | Flag | Description and default | | - | - | | `--forward-to string` | Local endpoint to forward events to | | `--recipient string` | Recipient pattern for temporary route (e.g., `*@domain.com`) | | `--route-id string` | Use existing route instead of creating temporary one | | `--skip-verify` | Skip SSL certificate verification for local endpoints when forwarding events (needs `--forward-to`) | | `--slim-output` | Slim down the payload for printing to the console | ### `routes trigger` This command has no command-specific flags. See [global flags](https://ahasend.com/docs/cli/configuration.md#global-flags). ### `routes update` | Flag | Description and default | | - | - | | `--enabled` | Enable (`--enabled`) or disable (`--enabled=false`) the route | | `--group-by-message-id` | Group related emails by message ID (`=false` to stop) | | `--include-attachments` | Include attachments in the webhook payload (`=false` to stop) | | `--include-headers` | Include headers in the webhook payload (`=false` to stop) | | `--name string` | New route name | | `--recipient string` | New recipient filter, `local@domain`, such as `*@example.com` | | `--strip-replies` | Strip reply content from emails (`=false` to stop) | | `--url string` | New webhook URL | ## Related Guides * [Install the CLI](https://ahasend.com/docs/cli/installation.md), [CLI authentication](https://ahasend.com/docs/cli/authentication.md), [Inbound routing setup](https://ahasend.com/docs/integrations/routing.md). * [Route payload](https://ahasend.com/docs/api-reference/routes/route-message.md), [Local route testing](https://ahasend.com/docs/cli/route-testing.md), [Signature verification](https://ahasend.com/docs/api-reference/webhooks/security.md). * [Retry policy](https://ahasend.com/docs/api-reference/webhooks/retry-policy.md), [CLI configuration and output](https://ahasend.com/docs/cli/configuration.md), [API authentication](https://ahasend.com/docs/api-reference/authentication.md). * [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.