> ## 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. # Create Route > Creates a new route for inbound email routing ## OpenAPI ````yaml /openapi.yaml POST /v2/accounts/{account_id}/routes openapi: 3.1.0 info: title: AhaSend API v2 description: > The AhaSend API v2 allows you to send transactional emails, manage domains, webhooks, routes, API keys, and view statistics. ## Authentication All API requests must be authenticated using a Bearer token in the Authorization header: ``` Authorization: Bearer aha-sk-64-CHARACTER-RANDOM-STRING ``` ## Scopes API keys have specific scopes that control access to different resources and actions: ### Message Scopes - `messages:send:all` - Send messages from any domain in the account - `messages:send:{domain}` - Send messages from a specific domain - `messages:cancel:all` - Cancel messages from any domain - `messages:cancel:{domain}` - Cancel messages from a specific domain - `messages:read:all` - Read messages from any domain - `messages:read:{domain}` - Read messages from a specific domain ### Domain Scopes - `domains:read` - Read all domains - `domains:write` - Create and update domains - `domains:delete:all` - Delete any domain - `domains:delete:{domain}` - Delete a specific domain ### Account Scopes - `accounts:read` - Read account information - `accounts:write` - Update account settings - `accounts:billing` - Access billing information - `accounts:members:read` - Read account members - `accounts:members:add` - Add account members - `accounts:members:update` - Update account members - `accounts:members:remove` - Remove account members ### Webhook Scopes - `webhooks:read:all` - Read all webhooks - `webhooks:read:{domain}` - Read webhooks for a specific domain - `webhooks:write:all` - Create and update webhooks - `webhooks:write:{domain}` - Create and update webhooks for a specific domain - `webhooks:delete:all` - Delete any webhook - `webhooks:delete:{domain}` - Delete webhooks for a specific domain ### Route Scopes - `routes:read:all` - Read all routes - `routes:read:{domain}` - Read routes for a specific domain - `routes:write:all` - Create and update routes - `routes:write:{domain}` - Create and update routes for a specific domain - `routes:delete:all` - Delete any route - `routes:delete:{domain}` - Delete routes for a specific domain ### Suppression Scopes - `suppressions:read` - Read suppressions - `suppressions:write` - Create suppressions - `suppressions:delete` - Delete suppressions - `suppressions:wipe` - Delete all suppressions (dangerous) ### SMTP Credentials Scopes - `smtp-credentials:read:all` - Read all SMTP credentials - `smtp-credentials:read:{domain}` - Read SMTP credentials for a specific domain - `smtp-credentials:write:all` - Create SMTP credentials - `smtp-credentials:write:{domain}` - Create SMTP credentials for a specific domain - `smtp-credentials:delete:all` - Delete any SMTP credentials - `smtp-credentials:delete:{domain}` - Delete SMTP credentials for a specific domain ### Statistics Scopes - `statistics-transactional:read:all` - Read all transactional statistics - `statistics-transactional:read:{domain}` - Read transactional statistics for a specific domain ### API Key Scopes - `api-keys:read` - Read API keys - `api-keys:write` - Create and update API keys - `api-keys:delete` - Delete API keys ## Rate Limiting - General API endpoints: 100 requests per second, 200 burst - Statistics endpoints: 1 request per second, 1 burst ## Pagination List endpoints use cursor-based pagination with the following parameters: - `limit`: Maximum number of items to return (default: 100, max: 100) - `cursor`: Pagination cursor for the next page ## Time Formats All timestamps must be in RFC3339 format, e.g., `2023-12-25T10:30:00Z` ## Idempotency POST requests support idempotency through the optional `Idempotency-Key` header. When provided: - The same request can be safely retried multiple times - Duplicate requests return the same response with `Idempotent-Replayed: true` - In-progress requests return HTTP 409 with `Idempotent-Replayed: false` - Failed requests return HTTP 412 with `Idempotent-Replayed: false` - Reusing a key with a different request payload returns HTTP 422 - Idempotency keys expire after 24 hours version: 2.0.0 contact: email: support@ahasend.com license: name: MIT identifier: MIT servers: - url: https://api.ahasend.com description: Production server security: - BearerAuth: [] tags: - name: Utility description: Utility endpoints for health checks and diagnostics - name: API Keys description: Manage API keys for authentication and access control - name: Domains description: Manage sending domains - name: Messages description: Send and manage transactional messages - name: Accounts description: Manage account settings and members - name: Suppressions description: Manage email suppressions - name: Routes description: Manage inbound email routing - name: Webhooks description: Manage webhook notifications - name: SMTP Credentials description: Manage SMTP authentication credentials - name: Statistics description: Access transactional email statistics - name: Message Events description: Webhooks for outbound message delivery events - name: Suppression Events description: Webhooks for suppression list changes - name: Domain Events description: Webhooks for domain configuration issues - name: Route Events description: Webhooks for inbound email routing paths: /v2/accounts/{account_id}/routes: post: tags: - Routes summary: Create Route description: Creates a new route for inbound email routing operationId: createRoute parameters: - name: account_id in: path required: true description: Account ID schema: type: string format: uuid - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRouteRequest' responses: '201': description: Route created successfully headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/CreatedRoute' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': $ref: '#/components/responses/IdempotencyConflict' '412': $ref: '#/components/responses/IdempotencyPreconditionFailed' '422': $ref: '#/components/responses/IdempotencyPayloadMismatch' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: - routes:write:all - routes:write:{domain} x-code-samples: - lang: go label: AhaSend Go SDK source: | package main import ( "context" "fmt" "log" "github.com/AhaSend/ahasend-go/api" "github.com/AhaSend/ahasend-go/models/requests" "github.com/google/uuid" ) func main() { // Create API client with authentication client := api.NewAPIClient( api.WithAPIKey("aha-sk-your-64-character-key"), ) accountID := uuid.New() // Create context for the API call ctx := context.Background() // Call the ping endpoint response, httpResp, err := client.RoutesAPI.CreateRoute( ctx, accountID, requests.CreateRouteRequest{ Name: "My Route", URL: "https://mystartup.com/tickets", Recipient: "ticket-*@mystartup.com", Enabled: true, Attachments: true, Headers: true, StripReplies: true, }, ) if err != nil { log.Fatalf("Error creating route: %v", err) } // Check response if httpResp.StatusCode == 201 { fmt.Printf("✅ Status: %d\n", httpResp.StatusCode) if response != nil { fmt.Printf("Created route: %#v\n", response) } } else { fmt.Printf("❌ Unexpected status code: %d\n", httpResp.StatusCode) } } components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: > Optional idempotency key for safe request retries. Must be a unique string for each logical request. Requests with the same key will return the same response. Keys expire after 24 hours. schema: type: string maxLength: 255 example: user-12345-create-domain-20240101 schemas: CreateRouteRequest: type: object required: - name - url - recipient properties: name: type: string maxLength: 255 description: Route name url: type: string format: uri description: Webhook URL for the route recipient: type: string maxLength: 255 description: Recipient filter attachments: type: boolean description: Whether to include attachments in webhooks default: false headers: type: boolean description: Whether to include headers in webhooks default: false group_by_message_id: type: boolean description: Whether to group by message ID default: false strip_replies: type: boolean description: Whether to strip reply content default: false enabled: type: boolean description: Whether the route is enabled default: true example: name: Support Route url: https://example.com/webhook recipient: support@example.com enabled: true CreatedRoute: allOf: - $ref: '#/components/schemas/Route' - type: object properties: secret: type: string description: Route signing secret. Returned only when the route is created. required: - secret ErrorResponse: type: object required: - message properties: message: type: string description: Error description example: message: Error message Route: type: object properties: object: type: string enum: - route description: Object type identifier id: type: string format: uuid description: Unique identifier for the route created_at: type: string format: date-time description: When the route was created updated_at: type: string format: date-time description: When the route was last updated name: type: string description: Route name url: type: string format: uri description: Webhook URL for the route recipient: type: string nullable: true description: Recipient filter attachments: type: boolean description: Whether to include attachments in route payload headers: type: boolean description: Whether to include headers in route payload group_by_message_id: type: boolean description: Whether to group by message ID strip_replies: type: boolean description: Whether to strip reply content enabled: type: boolean description: Whether the route is enabled success_count: type: integer description: Number of successful calls error_count: type: integer description: Number of unsuccessful calls errors_since_last_success: type: integer description: Number of consecutive failed calls last_request_at: type: string format: date-time nullable: true description: When the route was last called required: - object - id - created_at - updated_at - name - url - enabled headers: IdempotentReplayed: description: > Indicates whether this response is replayed from a previous identical request. - `true`: Response was replayed from cache (duplicate request) - `false`: Response from original processing or error state schema: type: string enum: - true - false responses: IdempotencyConflict: description: >- Request in progress - a request with this idempotency key is already being processed headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: A request with this idempotency key is already in progress IdempotencyPreconditionFailed: description: >- Original request failed - the request with this idempotency key previously failed and cannot be retried headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: >- The original request with this idempotency key failed and cannot be retried IdempotencyPayloadMismatch: description: Idempotency key was already used with a different request payload content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: idempotency key was already used with a different request payload securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING description: API key for authentication ````