> ## 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. # Preview a Segment via the API > Try AhaSend segment rules without saving them: get the number of contacts that the rules match now, and up to 10 of the matching contacts. The AhaSend API counts the contacts that a definition matches now, and returns up to 10 of them. Nothing is saved. Access requires `segments:read` and `contacts:read`, because a preview reads contacts by any rule. **Request:** * `definition` is required. It follows the same rules as in [Create Segment](https://ahasend.com/docs/api-reference/segments/create-segment.md). See [Definitions](https://ahasend.com/docs/api-reference/segments/overview.md#definitions). * `timezone` is the IANA time zone that relative times and days are read in. Without it, or with `null` or an empty string, they are read in `UTC`. **Response:** * `count` is the number of contacts that match, whatever their consent. A campaign can reach fewer of them. See [Members and reachable contacts](https://ahasend.com/docs/api-reference/segments/overview.md#members-and-reachable-contacts). * The count stops after 10 seconds, and `count` is then `null`. * `contacts` holds up to 10 matching contacts, in no particular order, each with `contact_id` and `email`. They are a separate read, so they come back also when `count` is `null`. `contacts` is empty when they cannot be read within 10 seconds. A refused definition or an unknown time zone answers `400`, and the message names each problem. ## Related Guides * [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Create Segment](https://ahasend.com/docs/api-reference/segments/create-segment.md). * [Segments API overview](https://ahasend.com/docs/api-reference/segments/overview.md), [API errors](https://ahasend.com/docs/api-reference/errors.md), [API rate limits](https://ahasend.com/docs/api-reference/rate-limits.md). ## OpenAPI ````yaml openapi.yaml POST /v2/accounts/{account_id}/segments/preview 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`. ### Segment Scopes - `segments:read` - Read segments, their members and a contact's segments, and preview a definition - `segments:write` - Create and update segments - `segments:delete` - Delete segments ### Segments A segment is a saved set of rules over the account's contacts: their fields, their list memberships, and the campaigns they received, opened or clicked. AhaSend keeps its members up to date as that data changes, usually within a minute; rules about campaigns follow within an hour of a send, and relative times such as `30 days ago` are read again on a schedule. Membership is the rule match only, whatever the contact's consent: a campaign to a segment reaches the members who are enabled, not unsubscribed, not found invalid, and either confirmed on at least one list or on no list at all. A contact who unsubscribed from or complained on every list they were on, or has not confirmed a double opt-in, is not reached. A contact who unsubscribes from a segment send, or reports it as spam, gets no more marketing email from the account. ### 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 A request over the limit gets HTTP 429 with a `Retry-After` header: the number of seconds to wait before retrying. ## 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. - Create Segment and Test Campaign store and replay a 2xx only. A 4xx is not stored: it releases the key, so a retry with the same key runs again. - 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: Segments description: >- Manage segments, the saved rules that keep a set of contacts up to date, and read their 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}/segments/preview: post: tags: - Segments summary: Preview Segment description: | Returns how many contacts a definition matches now, and up to 10 of them, without saving anything. The count stops after 10 seconds and is null then; the contacts are a separate read, returned either way. `contacts` is empty when they cannot be read within 10 seconds. A preview changes nothing, and it reads contacts by any rule, so it needs `segments:read` and `contacts:read`. operationId: previewSegment parameters: - name: account_id in: path required: true description: Account ID schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreviewSegmentRequest' responses: '200': description: What the definition matches now content: application/json: schema: $ref: '#/components/schemas/SegmentPreview' '400': description: | Invalid request body, an unknown time zone, or a definition that is refused. The message names every problem of the definition by its path. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: >- conditions[0].field: the account has no contact field "city"; conditions[1].value: must be a list id '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Missing `segments:read` or `contacts:read` scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: - segments:read - contacts:read x-code-samples: - lang: go label: AhaSend Go SDK source: | package main import ( "context" "fmt" "log" "os" "github.com/AhaSend/ahasend-go" "github.com/AhaSend/ahasend-go/api" "github.com/AhaSend/ahasend-go/models/common" "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() // Nothing is saved. Count is nil when the contacts cannot be counted // within 10 seconds. response, _, err := client.SegmentsAPI.PreviewSegment(ctx, accountID, requests.PreviewSegmentRequest{ Definition: common.SegmentDefinition{ SchemaVersion: common.SegmentSchemaVersion, Match: common.SegmentMatchAll, Conditions: []common.SegmentRule{ {Condition: &common.SegmentCondition{ Field: common.SegmentFieldCreatedAt, Op: common.SegmentOpAfter, Value: &common.SegmentValue{String: ahasend.String("30 days ago")}, }}, }, }, }) if err != nil { log.Fatalf("Error previewing segment: %v", err) } if response.Count != nil { fmt.Printf("%d contacts match\n", *response.Count) } for _, contact := range response.Contacts { fmt.Println(contact.Email) } } - lang: javascript label: Node.js 22+ (AhaSend SDK) source: > import { AhaSendClient } from "@ahasend/sdk"; const client = AhaSendClient.fromEnv(); // Nothing is saved. count is null when the contacts cannot be counted within 10 seconds. const preview = await client.segments.preview({ definition: { schema_version: 1, match: "all", conditions: [{ field: "created_at", op: "after", value: "30 days ago" }], }, }); console.log("Segment previewed.", { count: preview.count, shown: preview.contacts.length }); components: schemas: PreviewSegmentRequest: type: object additionalProperties: false description: A definition to try. Nothing is saved. required: - definition properties: definition: $ref: '#/components/schemas/SegmentDefinition' timezone: type: - string - 'null' description: >- The IANA time zone that relative times and days are read in. Null, omission and an empty string all read them in `UTC`. SegmentPreview: type: object additionalProperties: false required: - object - count - contacts properties: object: type: string enum: - segment_preview description: Object type identifier count: type: - integer - 'null' minimum: 0 description: >- The contacts the definition matches now, whatever their consent. Null when they cannot be counted within 10 seconds. contacts: type: array maxItems: 10 description: >- Up to 10 of the matching contacts, in no particular order. They are returned also when `count` is null, and are empty when they cannot be read within 10 seconds. items: $ref: '#/components/schemas/SegmentPreviewContact' 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 SegmentDefinition: type: object additionalProperties: false description: | The rules of a segment. The root group holds conditions and groups; a group holds conditions only, so groups nest one level deep. A definition has at most 50 conditions in all, and at most 5 of them are `campaign`, `any_campaign` or `campaign_count` conditions. An unknown key, or a `schema_version` other than 1, is refused. A refused definition is answered with 400 and a message that names each problem by its path, such as `conditions[3].value`. required: - schema_version - match - conditions properties: schema_version: type: integer enum: - 1 description: The version of this format match: type: string enum: - all - any description: Whether a contact must match all of the conditions or any of them conditions: type: array minItems: 1 items: oneOf: - $ref: '#/components/schemas/SegmentCondition' - $ref: '#/components/schemas/SegmentGroup' example: schema_version: 1 match: all conditions: - field: attributes.country op: equal value: DE - field: created_at op: after value: 30 days ago - field: list op: in value: 6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b - match: any conditions: - field: campaign op: opened value: 9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b - field: any_campaign op: clicked value: 14 days ago - field: campaign_count op: opened_at_least value: count: 3 since: 90 days ago SegmentPreviewContact: type: object additionalProperties: false required: - contact_id - email properties: contact_id: type: string format: uuid description: The contact email: type: string format: email description: The contact's normalized email address SegmentCondition: type: object additionalProperties: false description: | One rule. `field` names what it reads: - `email`, `first_name`, `last_name`, `created_at` (when the contact was created), or `attributes.` for a contact field of the account. The operators and values are those of the field's type: text fields take `equal`, `not_equal`, `contains`, `not_contains`, `begins_with`, `not_begins_with`, `ends_with`, `not_ends_with`, `is_empty` and `is_not_empty`; number fields `equal`, `not_equal`, `less`, `less_or_equal`, `greater` and `greater_or_equal`; date and timestamp fields and `created_at` `equal`, `not_equal`, `before`, `before_or_on`, `after` and `after_or_on`, with a date such as `2024-06-15` or a relative time such as `today` or `30 days ago`, and timestamp fields and `created_at` also a time such as `2 hours from now`; boolean fields `is_true` and `is_false`. Custom date, number, timestamp and boolean fields also take `is_null` and `is_not_null`; `email`, `first_name`, `last_name`, `created_at` and custom text fields do not. A negated operator also matches a contact that has no value for the field. - Custom date fields also take two rules that read only the month and day, so the year does not matter: `month_is` with a month from 1 (January) to 12 (December), and `anniversary_within` with a number of days N from 0 to 365, which matches when the month and day fall on today or one of the next N days in the segment's time zone (`0` is today only). A 29 February date counts as 28 February in a year without one. Both take a whole number as `value`. Both read a stored value that starts with a `YYYY-MM-DD` date, as the API and imports store it; any other value never matches. The members of an `anniversary_within` segment move to the new day shortly after midnight in its time zone, usually within about half an hour. - `list` with `in` or `not_in` and a list ID. `in` means a `confirmed` membership of that list. - `campaign` with `received`, `not_received`, `opened`, `not_opened`, `clicked` or `not_clicked` and a campaign ID. `received` means the campaign was delivered to the contact. `not_opened` and `not_clicked` match only contacts who received the campaign. - `any_campaign` with `received`, `opened`, `clicked`, `not_opened` or `not_clicked` and a relative time such as `14 days ago`: `received`, `opened` and `clicked` match at least one such event since then; `not_opened` and `not_clicked` match a contact who received a campaign since then and opened (clicked) none since then. - `campaign_count` with `received_at_least`, `received_fewer_than`, `opened_at_least`, `opened_fewer_than`, `clicked_at_least` or `clicked_fewer_than` and a `SegmentCampaignCount` object such as `{"count": 3, "since": "90 days ago"}`: the number of campaigns sent since then that the contact received, opened or clicked. A campaign counts from the time it started sending, whenever the contact received, opened or clicked it, and several opens or clicks of one campaign count once. `received_fewer_than`, `opened_fewer_than` and `clicked_fewer_than` match only a contact who received at least one campaign sent since then. Opens and clicks by bots do not count. A list, campaign or contact field that a segment uses cannot be deleted until no segment uses it. required: - field - op properties: field: type: string description: >- `email`, `first_name`, `last_name`, `created_at`, `attributes.`, `list`, `campaign`, `any_campaign` or `campaign_count` op: type: string enum: - equal - not_equal - contains - not_contains - begins_with - not_begins_with - ends_with - not_ends_with - is_empty - is_not_empty - less - less_or_equal - greater - greater_or_equal - before - before_or_on - after - after_or_on - is_null - is_not_null - is_true - is_false - month_is - anniversary_within - in - not_in - received - not_received - opened - not_opened - clicked - not_clicked - received_at_least - received_fewer_than - opened_at_least - opened_fewer_than - clicked_at_least - clicked_fewer_than description: The operator, one that applies to `field` value: oneOf: - type: - string - number - boolean - 'null' - $ref: '#/components/schemas/SegmentCampaignCount' description: >- The value the operator compares with. Left out, or null, for an operator that takes none, such as `is_empty`. A month for `month_is` and a number of days for `anniversary_within`, each a whole number. A `SegmentCampaignCount` object for `campaign_count`. SegmentGroup: type: object additionalProperties: false description: A nested group of conditions. A group cannot hold another group. required: - match - conditions properties: match: type: string enum: - all - any description: >- Whether a contact must match all of the group's conditions or any of them conditions: type: array minItems: 1 items: $ref: '#/components/schemas/SegmentCondition' SegmentCampaignCount: type: object additionalProperties: false description: >- The value of a `campaign_count` condition. A missing or unknown property is refused. required: - count - since properties: count: type: integer minimum: 1 maximum: 1000 description: >- The number of campaigns, a whole number from 1 to 1000, or from 2 for `received_fewer_than`. since: type: string description: | When the window starts: a relative time of the form `M days ago`, `M weeks ago`, `M months ago` or `M years ago`, with M from 1 to 365 days, 52 weeks, 12 months or 1 year. It starts at the beginning of its day in the segment's time zone. example: 90 days ago 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.