> ## 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. # Send a Campaign Test via the API > Send a test of a draft AhaSend marketing campaign to up to 5 addresses to check it in a real inbox. An account can send 50 test emails per day (UTC). The AhaSend API sends a test of a draft campaign. Access requires `campaigns:send`. **Addresses:** * `to` holds 1 to 5 addresses. Addresses that differ only in case count once. * An entry can have a display name, such as `Ann `. The test goes to the address only. **What the test holds:** * Each address gets the design with placeholders for the contact's fields. * The links in the test lead to a contact that does not exist, so a click on the unsubscribe link does not unsubscribe anyone. **When the API refuses the test:** * The campaign must be a draft. Any other status answers `409`. * A campaign with issues is refused with `400`, and the response holds the issues. The issue `unsubscribe_link_missing` does not stop a test. See [Issues](/docs/api-reference/campaigns/overview#issues). * The domain of the sender must be verified and not paused. If not, the test is refused with `400`. * An account that is blocked until a person acts, for example a sub-account in the `parent-suspended` status, whose parent account is suspended, cannot send tests: the test is refused with `400`. An account that is blocked only until it pays, for example one with no credits left, can still send tests, because tests use no credits. **Daily limit:** * Your account can send 50 test emails per day (UTC). Each address of a test counts as one test email. Test sends from the API and from the dashboard count together. * The API refuses the whole test when its addresses would take the day's total over 50. For example, with 48 test emails used, a test to 5 addresses is refused, and a test to 2 addresses is sent. * The API answers `429` when it refuses a test for the limit. Its message currently reads `daily test send limit reached`. Backoff does not clear this `429`. A test to fewer addresses can still fit in the test emails left for the day, as in the example above. Otherwise, the limit clears when the UTC day changes. To plan for it, keep count of the test emails you send each UTC day. A `429` from Test Campaign that stays after backoff is the daily limit. * An address that the mail server refused still counts, and so does a test with `result_unknown`. A test that sent nothing (`502`) does not count. **Response:** * `sent_to` lists the addresses that the mail server accepted, and `failed` lists the addresses it refused, each with the reason. An address in `failed` is given as the mail server reported it, so it can differ from the addresses in `to`. * When `result_unknown` is `true`, the mail server took the request, but its answer could not be read. The test may have gone out, and `sent_to` and `failed` are empty. Check the inboxes before you send another test. * When the mail server could not take the test, the API answers `502` and nothing was sent. Retry the request. **Idempotency:** This operation accepts an `Idempotency-Key` header. A `2xx` answer is stored, so a retry with the same key replays it and sends nothing again. Unlike other operations, a `4xx` answer is not stored. A retry with the same key, for example after the daily limit resets, gets a new answer. A `502` is not stored either, so you can retry it with the same key. See [Idempotency](/docs/api-reference/idempotency). ## Related Guides * [API authentication](/docs/api-reference/authentication), [Permission scopes](/docs/api-reference/scopes), [Idempotency](/docs/api-reference/idempotency). * [Send Campaign](/docs/api-reference/campaigns/send-campaign), [API errors](/docs/api-reference/errors), [API rate limits](/docs/api-reference/rate-limits). ## OpenAPI ````yaml openapi.yaml POST /v2/accounts/{account_id}/campaigns/{campaign_id}/test 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 the account's suppressions except protected ones (dangerous) ### Template Scopes - `templates:read` - Read transactional templates, their drafts and their published versions, and campaign templates - `templates:write` - Create and update transactional templates, and publish, discard and restore their drafts; create and update campaign templates - `templates:delete` - Delete transactional templates and campaign templates ### Campaign Scopes - `campaigns:read` - Read campaigns, their stats and their recipients - `campaigns:write` - Create, update and duplicate campaigns - `campaigns:delete` - Delete draft campaigns - `campaigns:send` - Send, unschedule and test-send campaigns ### Contact Scopes - `contacts:read` - Read contacts - `contacts:write` - Create and update contacts - `contacts:delete` - Delete contacts ### Contact lifecycle and attributes Contacts are account-global. A contact created through this API joins no list on its own; campaigns target lists, so add it to one with the Lists endpoints before a campaign can reach it. Contact subscription state and suppression records are independent: creating, updating, unsubscribing, resubscribing, or deleting a contact never creates, changes, or removes complaint, permanent, or protected suppressions. Prefer unsubscribe over delete when the goal is only to stop marketing mail, because unsubscribe is reversible and preserves contact history. Writable attribute keys and types come from the account's contact-attribute definitions managed in the dashboard; this API does not expose property definition CRUD. Writes accept only canonical values for those definitions, while reads remain legacy-safe and can return any recursively nested JSON value previously stored. An email used as `{id_or_email}` is a raw SDK argument and must be percent-encoded exactly once as a URL path segment by an HTTP client. For example, do not pre-encode `user+tag@example.com` before passing it to an SDK that encodes path parameters. ### List Scopes - `lists:read` - Read lists and list membership - `lists:write` - Create and update lists, and add or remove their contacts - `lists:delete` - Delete lists ### Lists and membership A list is a static, private, single opt-in container of contacts, and it is what a campaign targets. A membership carries its own `subscription_status` (`unconfirmed`, `confirmed`, `unsubscribed`, or `complained`), which is per-list consent and is independent of the contact's account-wide `unsubscribed` flag. A membership created without a status named is `confirmed`, because that is what a campaign reaches. `complained` is the mailbox provider's verdict, never writable, and a membership holding it is frozen. Deleting a list keeps its memberships, so an unsubscribe survives it. Removing a contact from a list deletes the membership row and discards that record with it, which is why unsubscribing is the reversible way to stop marketing mail on one list. Expanding a list's members with `include_contacts=true` requires `contacts:read` in addition to `lists:read`. ### 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 ### Sub-Account Scopes - `sub-accounts:read` - List and read sub accounts under the parent - `sub-accounts:write` - Create and update sub accounts - `sub-accounts:delete` - Soft-delete sub accounts - `sub-accounts:suspend` - Pause and resume sub accounts, and unpause their domains - `sub-accounts:usage` - Read per-sub-account usage and allocated cost - `sub-account-api-keys:read` - List and read API keys owned by sub accounts - `sub-account-api-keys:write` - Create and update API keys owned by sub accounts - `sub-account-api-keys:delete` - Delete API keys owned by sub accounts ## 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) - `after`: Pass `pagination.next_cursor` to fetch the next page - `before`: Pass `pagination.previous_cursor` to fetch the previous page `after` and `before` are mutually exclusive. A legacy `cursor` query may be accepted by parts of the server for backwards compatibility, but it is not part of the v2 public contract. ## Time Formats All timestamps must be in RFC3339 format, e.g., `2023-12-25T10:30:00Z` ## Idempotency The operations that explicitly declare the optional `Idempotency-Key` header support idempotency. Other POST operations do not gain idempotency implicitly. When the header is provided: - A fresh execution does not return `Idempotent-Replayed`. - A completed stored response is replayed with its original status and body and `Idempotent-Replayed: true`. - An unexpired in-progress execution returns HTTP 409 with `Idempotent-Replayed: false` and a positive integer `Retry-After` header. - Reusing a key with a different HTTP method, resolved request path, or request body returns HTTP 422. That response has neither `Idempotent-Replayed` nor `Retry-After`. - For ordinary idempotent operations, deterministic 2xx and 4xx outcomes produced after the idempotency middleware are stored and replayed. Authentication and IP-allow-list failures happen before idempotency and are therefore not stored. - The two secret-bearing API-key create operations use manual encrypted completion. They store and replay a successful 201, including the same one-time `secret_key`; a controller-produced 4xx is not stored and leaves the key in progress until its execution lease expires. - Server errors (5xx), handler failures, and panics are not stored. The key is released so retrying the same request with the same key re-executes it. The v2 API does not use an HTTP 412 failed-key tombstone. - Idempotency keys for non-secret responses expire after 24 hours. - Encrypted API-key creation replay responses expire after 5 minutes. ## IP Allow Lists Each API key can carry an `ip_allow_list`: a set of source IPs that restrict where the key may authenticate from. - Entries are CIDR blocks (e.g. `203.0.113.0/24`) or bare IPv4/IPv6 addresses (stored as a `/32` or `/128`). They are canonicalized and de-duplicated; the allow-all prefixes `0.0.0.0/0` and `::/0` are rejected, and at most 100 entries are allowed after de-duplication (a longer list is rejected with HTTP 400). - An empty list (the default) places no restriction. - When the list is non-empty, any authenticated request whose client IP is not covered by an entry is rejected with HTTP 403 on every v2 endpoint, regardless of the key's scopes. - Manage the list with the `ip_allow_list` field on the API-key create and update endpoints (including the sub-account API-key endpoints). - When a key updates its own `ip_allow_list` to a value that excludes the caller's current IP, the update is rejected with HTTP 409 to prevent self-lockout. Updating a sub-account key from a parent key has no such guard. 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: Contacts description: Read, create, update, batch upsert, and delete account-global contacts - name: Templates description: >- Create, change, publish and delete the account's transactional templates, and read them with their drafts, their published versions and the variables a send must supply - name: Campaign Templates description: >- Create, change, read and delete the account's campaign templates, the designs a campaign copies when it is made from one - name: Campaigns description: >- Create, change, read, duplicate, delete, test and send the account's marketing campaigns, and read their stats and recipients - name: Lists description: Manage contact lists and the contacts on them - 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}/campaigns/{campaign_id}/test: post: tags: - Campaigns summary: Test Campaign description: | Sends a test of a draft campaign to up to 5 addresses. Each address gets the design with placeholders for the contact's fields; its links lead to a contact that does not exist. A campaign with any issue but `unsubscribe_link_missing` is refused with the issues. An account can send 50 test emails per day (UTC), counted per address, from the API and the dashboard together. An address the mail server refused still counts; a test that sent nothing (502) does not. With an `Idempotency-Key`, a 2xx answer is stored and replayed, so a retry with the same key sends nothing again. Unlike other operations, a 4xx answer is not stored: it releases the key, so a retry with the same key, for example after the daily limit resets, is answered afresh. operationId: testCampaign parameters: - name: account_id in: path required: true description: Account ID schema: type: string format: uuid - name: campaign_id in: path required: true description: Campaign ID schema: type: string format: uuid - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestCampaignRequest' responses: '200': description: >- What the test send did. With `result_unknown`, the test may have gone out. headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/CampaignTest' '400': description: >- Invalid campaign_id, an invalid body or address, no address or more than 5, a campaign with issues (with `issues`), a sender domain that is paused or no longer verified, or an account that cannot send content: application/json: schema: $ref: '#/components/schemas/CampaignNotReady' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Missing `campaigns:send` scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Campaign not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': $ref: '#/components/responses/CampaignConflict' '422': $ref: '#/components/responses/IdempotencyPayloadMismatch' '429': description: >- Too many requests, or the account's daily limit of 50 test emails is reached (`daily test send limit reached`). Neither is stored, so a retry may use the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: >- The mail server could not take the test, and nothing was sent. Retry, with the same `Idempotency-Key` if you sent one. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: - campaigns:send x-code-samples: - lang: go label: AhaSend Go SDK source: | package main import ( "context" "fmt" "log" "os" "github.com/AhaSend/ahasend-go/api" "github.com/AhaSend/ahasend-go/models/requests" "github.com/google/uuid" ) func main() { client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY"))) accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID")) ctx := context.Background() campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111") response, _, err := client.CampaignsAPI.TestCampaign(ctx, accountID, campaignID, requests.TestCampaignRequest{ To: []string{"Ann ", "bob@yourdomain.com"}, }) if err != nil { log.Fatalf("Error sending test: %v", err) } if response.ResultUnknown { fmt.Println("The test may have gone out; check the inboxes before you send another") return } fmt.Printf("Sent to %v\n", response.SentTo) for _, failure := range response.Failed { fmt.Printf("Refused %s: %s\n", failure.Email, failure.Message) } } - lang: javascript label: Node.js 22+ (AhaSend SDK) source: > import { AhaSendClient } from "@ahasend/sdk"; const client = AhaSendClient.fromEnv(); // The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries. const campaignId = "00000000-0000-4000-8000-000000000014"; const result = await client.campaigns.test(campaignId, { to: ["reviewer@example.com"] }); console.log("Campaign test sent.", { sentTo: result.sent_to, failed: result.failed.length, resultUnknown: result.result_unknown, }); 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. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time `secret_key`, so successful encrypted replay responses for those operations expire after 5 minutes. schema: type: string maxLength: 255 example: user-12345-create-domain-20240101 schemas: TestCampaignRequest: type: object additionalProperties: false required: - to description: The addresses to send a test to. properties: to: type: array minItems: 1 items: type: string description: >- 1 to 5 addresses, counted after addresses that differ only in case are dropped. An entry may carry a display name, such as `Ann `; the test goes to the address alone. CampaignTest: type: object required: - object - sent_to - failed - result_unknown description: What a test send did. properties: object: type: string enum: - campaign_test description: Object type identifier sent_to: type: array items: type: string description: The addresses the mail server accepted failed: type: array items: $ref: '#/components/schemas/CampaignTestFailure' description: The addresses the mail server refused result_unknown: type: boolean description: >- True when the mail server took the request but its answer could not be read. The test may have gone out; `sent_to` and `failed` are empty. Check the inboxes before you send another. CampaignNotReady: type: object required: - message description: >- A refusal. A campaign with issues is refused with `campaign is not ready to send` and the issues that block the request; every other refusal has only `message`. properties: message: type: string description: Error message issues: type: array items: $ref: '#/components/schemas/CampaignIssue' description: >- The issues that block the request, in the order of `CampaignIssue`. For a test, every issue but `unsubscribe_link_missing`. example: message: campaign is not ready to send issues: - code: subject_missing message: Add a subject before you send the campaign. ErrorResponse: type: object description: | Human-readable API error. The server currently sends no stable machine error code. In particular, clients must not parse `message` to distinguish IP-allow-list, scope, ownership, plan, self-lockout, suppression-duplicate, or other errors that share an HTTP status. additionalProperties: false required: - message properties: message: type: string description: Error description example: message: Error message CampaignTestFailure: type: object required: - email - message description: An address the mail server refused. properties: email: type: string description: >- The address as the mail server reported it, which can be one the request did not hold. message: type: string description: Why the address was refused CampaignIssue: type: object required: - code - message description: A reason the campaign cannot be sent yet. properties: code: type: string enum: - sender_missing - lists_missing - subject_missing - preheader_missing - design_missing - text_broken - unsubscribe_link_missing description: > - `sender_missing`: the campaign has no complete sender, or its domain was deleted. - `lists_missing`: the campaign has no list that still exists. - `subject_missing`: the campaign has no subject. - `preheader_missing`: the campaign has no preview text. - `design_missing`: the campaign has no design, or its design has no HTML. - `text_broken`: the subject, the preview text or the design holds template syntax that cannot be rendered, so every message would fail. - `unsubscribe_link_missing`: the HTML does not use `{{ unsubscribe_url }}`, with or without filters. message: type: string description: What to do, in the words the dashboard uses. headers: IdempotentReplayed: description: > Indicates that this response is a stored replay of a previous identical request. When this header is absent, the response is not a stored replay. Ordinary fresh responses do not send `false`; that value is reserved for an in-progress 409. schema: type: string enum: - 'true' IdempotencyRetryAfter: description: | Positive whole number of seconds after which the in-progress execution lease may be retried with the same key and unchanged request. schema: type: integer minimum: 1 responses: CampaignConflict: description: | Either the campaign's status does not allow the request (for most requests, the campaign is not a draft; for an unschedule, it is not validating or scheduled, or it has queued mail), or an execution with this idempotency key is still in progress. The in-progress case is identified only by `Idempotent-Replayed: false` plus a positive integer `Retry-After`; retry it after that many seconds with the same key. A new status conflict has neither header; a stored replay of one has `Idempotent-Replayed: true` (a test send's status conflict is not stored, so it is never replayed). The message is not a stable discriminator. headers: Idempotent-Replayed: description: | `false` with a positive `Retry-After` means an execution is in progress. `true` means a stored status 409 was replayed. Absent means a fresh status conflict. schema: type: string enum: - 'true' - 'false' Retry-After: $ref: '#/components/headers/IdempotencyRetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: campaign is not a draft IdempotencyPayloadMismatch: description: | Idempotency key was already used with a different HTTP method, resolved request path, or request body. This response includes neither `Idempotent-Replayed` nor `Retry-After`. 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. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.