AhaSend SMTP Credentials API

openapi: 3.2.0
info:
  title: AhaSend API v2 SMTP Credentials API
  description: The AhaSend API v2 allows you to send transactional emails, manage domains, webhooks, routes, API keys, and view statistics.
  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: SMTP Credentials
  description: Manage SMTP authentication credentials
paths:
  /v2/accounts/{account_id}/smtp-credentials:
    get:
      summary: Get SMTP Credentials
      description: 'Returns a list of SMTP credentials for the account. The global read role

        sees all credentials; domain-scoped roles return credentials associated

        with at least one authorized domain.'
      operationId: getSMTPCredentials
      tags:
      - SMTP Credentials
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: Maximum number of items to return (1-100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: after
        in: query
        description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
        schema:
          type: string
      - name: before
        in: query
        description: Pagination cursor for the previous page.
        schema:
          type: string
      security:
      - BearerAuth:
        - smtp-credentials:read:all
      - BearerAuth:
        - smtp-credentials:read:{domain}
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SMTPCredentialsAPI.GetSMTPCredentials(\n    ctx,\n    accountID,\n    nil,\n    nil,\n  )\n  if err != nil {\n    log.Fatalf(\"Error getting SMTP credentials: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"SMTP credentials: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const page = await client.smtpCredentials.list({ limit: 20 });

          console.log("SMTP credentials listed.", { count: page.data.length });

          '
      responses:
        '200':
          description: List of SMTP credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSMTPCredentialsResponse'
        '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'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create SMTP Credential
      description: 'Creates a new SMTP credential for SMTP authentication. A `scoped`

        credential requires at least one domain and the key must have write

        permission for every supplied domain. A `global` credential requires

        `smtp-credentials:write:all`; supplied domains are accepted but ignored,

        and the response contains `domains: []`. SMTP credentials have no

        update endpoint.'
      operationId: createSMTPCredential
      tags:
      - SMTP Credentials
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/IdempotencyKey'
      security:
      - BearerAuth:
        - smtp-credentials:write:all
      - BearerAuth:
        - smtp-credentials:write:{domain}
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/AhaSend/ahasend-go/models/requests\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SMTPCredentialsAPI.CreateSMTPCredential(\n    ctx,\n    accountID,\n    requests.CreateSMTPCredentialRequest{\n      Name: \"My SMTP Credential\",\n      Scope: \"global\",\n      Sandbox: true,\n    },\n  )\n  if err != nil {\n    log.Fatalf(\"Error creating SMTP credentials: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 201 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Created SMTP credentials: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: "import { AhaSendClient } from \"@ahasend/sdk\";\n\nconst client = AhaSendClient.fromEnv();\nconst credential = await client.smtpCredentials.create(\n  { name: \"Production SMTP\", scope: \"global\" },\n  { idempotencyKey: \"sdk-sample-create-smtp-credential\" },\n);\nconsole.log(\"SMTP credential created.\", { id: credential.id, name: credential.name });\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSMTPCredentialRequest'
      responses:
        '201':
          description: SMTP credential created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedSMTPCredential'
        '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'
        '422':
          $ref: '#/components/responses/IdempotencyPayloadMismatch'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/accounts/{account_id}/smtp-credentials/{smtp_credential_id}:
    get:
      summary: Get SMTP Credential
      description: 'Returns a specific SMTP credential by ID. Access requires the global

        read role or a read role matching at least one associated domain.'
      operationId: getSMTPCredential
      tags:
      - SMTP Credentials
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: smtp_credential_id
        in: path
        required: true
        description: SMTP Credential ID
        schema:
          type: string
          format: uuid
      security:
      - BearerAuth:
        - smtp-credentials:read:all
      - BearerAuth:
        - smtp-credentials:read:{domain}
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n  smtpCredentialID := uuid.MustParse(\"0194f7ac-2f6a-7d29-9f0c-9a27b19f2d1c\")\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SMTPCredentialsAPI.GetSMTPCredential(\n    ctx,\n    accountID,\n    smtpCredentialID,\n  )\n  if err != nil {\n    log.Fatalf(\"Error getting SMTP credentials: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"SMTP credentials: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const credentialId = "00000000-0000-4000-8000-000000000008";

          const credential = await client.smtpCredentials.get(credentialId);

          console.log("SMTP credential found.", { id: credential.id, name: credential.name });

          '
      responses:
        '200':
          description: SMTP credential details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMTPCredential'
        '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'
        '404':
          description: SMTP credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete SMTP Credential
      description: 'Deletes an SMTP credential. Access requires the global delete role or a

        delete role matching at least one associated domain.'
      operationId: deleteSMTPCredential
      tags:
      - SMTP Credentials
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: smtp_credential_id
        in: path
        required: true
        description: SMTP Credential ID
        schema:
          type: string
          format: uuid
      security:
      - BearerAuth:
        - smtp-credentials:delete:all
      - BearerAuth:
        - smtp-credentials:delete:{domain}
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n  smtpCredentialID := uuid.MustParse(\"0194f7ac-2f6a-7d29-9f0c-9a27b19f2d1c\")\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SMTPCredentialsAPI.DeleteSMTPCredential(\n    ctx,\n    accountID,\n    smtpCredentialID,\n  )\n  if err != nil {\n    log.Fatalf(\"Error deleting SMTP credentials: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Deleted SMTP credentials: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const credentialId = "00000000-0000-4000-8000-000000000008";

          const result = await client.smtpCredentials.delete(credentialId);

          console.log("SMTP credential deleted.", { message: result.message });

          '
      responses:
        '200':
          description: SMTP credential deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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'
        '404':
          description: SMTP credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  headers:
    IdempotencyInProgress:
      description: 'Identifies an idempotency-key execution that is still in progress. This

        header is emitted only on the specialized HTTP 409 response.

        '
      schema:
        type: string
        enum:
        - 'false'
    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
    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'
  schemas:
    CreatedSMTPCredential:
      allOf:
      - $ref: '#/components/schemas/SMTPCredential'
      - type: object
        properties:
          password:
            type: string
            description: SMTP password. Returned only when the credential is created.
        required:
        - password
    CreateSMTPCredentialRequest:
      type: object
      required:
      - name
      - scope
      properties:
        name:
          type: string
          maxLength: 255
          description: Credential name
        sandbox:
          type: boolean
          description: Whether this is a sandbox credential
          default: false
        scope:
          type: string
          enum:
          - global
          - scoped
          description: Credential scope - "global" or "scoped"
        domains:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'For `scoped`, a non-empty array is required. For `global`, this may

            be omitted, null, empty, or non-empty; supplied values are accepted

            but ignored.

            '
      allOf:
      - if:
          properties:
            scope:
              const: scoped
          required:
          - scope
        then:
          required:
          - domains
          properties:
            domains:
              type: array
              minItems: 1
              items:
                type: string
      example:
        name: Production SMTP
        scope: global
    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
    SMTPCredential:
      type: object
      properties:
        object:
          type: string
          enum:
          - credential_smtp
          description: Object type identifier
        id:
          type: string
          format: uuid
          description: Unique identifier for the SMTP credential
        created_at:
          type: string
          format: date-time
          description: When the credential was created
        updated_at:
          type: string
          format: date-time
          description: When the credential was last updated
        name:
          type: string
          description: Credential name
        username:
          type: string
          description: SMTP username
        sandbox:
          type: boolean
          description: Whether this is a sandbox credential
        scope:
          type: string
          enum:
          - global
          - scoped
          description: Credential scope
        domains:
          type: array
          items:
            type: string
          description: Domains this credential can send from. Always present; global credentials return an empty array.
      required:
      - object
      - id
      - created_at
      - updated_at
      - name
      - username
      - sandbox
      - scope
      - domains
    PaginatedSMTPCredentialsResponse:
      type: object
      required:
      - object
      - data
      - pagination
      properties:
        object:
          type: string
          enum:
          - list
          description: Object type identifier
        data:
          type: array
          items:
            $ref: '#/components/schemas/SMTPCredential'
          description: Array of SMTP credentials
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    SuccessResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Success message
      example:
        message: Operation completed successfully
    PaginationInfo:
      type: object
      required:
      - has_more
      properties:
        has_more:
          type: boolean
          description: Whether more items exist after the last item of this page
        next_cursor:
          type: string
          description: Pass as `after` to fetch the next page
        previous_cursor:
          type: string
          description: Pass as `before` to fetch the previous page; absent on a `before` page when the start of the list has been reached
      example:
        has_more: true
        next_cursor: eyJpZCI6MTIzNH0=
  responses:
    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
    IdempotencyConflict:
      description: 'Request in progress. This response always includes

        `Idempotent-Replayed: false` and a positive integer `Retry-After`.

        Clients must use that header tuple, not the human-readable message, to

        distinguish this retryable idempotency state from other HTTP 409s.

        '
      headers:
        Idempotent-Replayed:
          $ref: '#/components/headers/IdempotencyInProgress'
        Retry-After:
          $ref: '#/components/headers/IdempotencyRetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: A request with this idempotency key is already in progress
  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
  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.

        '