> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Domain

> Add a new sending domain to your account for email authentication using the AutoSend API.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.autosend.com/v1/domains \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "domain": "example.com",
      "regionKey": "us-east-1"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.autosend.com/v1/domains"

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  payload = {
      "domain": "example.com",
      "regionKey": "us-east-1",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.autosend.com/v1/domains", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      domain: "example.com",
      regionKey: "us-east-1",
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.autosend.com/v1/domains",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
      "domain" => "example.com",
      "regionKey" => "us-east-1",
    ]),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer <token>",
      "Content-Type: application/json",
    ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    payload, _ := json.Marshal(map[string]string{
      "domain":    "example.com",
      "regionKey": "us-east-1",
    })

    req, _ := http.NewRequest("POST", "https://api.autosend.com/v1/domains", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  HttpClient client = HttpClient.newHttpClient();

  String body = "{\"domain\": \"example.com\", \"regionKey\": \"us-east-1\"}";

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.autosend.com/v1/domains"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(body))
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "uri"
  require "json"

  uri = URI.parse("https://api.autosend.com/v1/domains")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.request_uri)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = JSON.generate({ domain: "example.com", regionKey: "us-east-1" })

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "60d5ec49f1b2c72d9c8b2222",
      "domainName": "example.com",
      "verificationStatus": "PENDING_CONFIGURATION",
      "ownershipVerified": false,
      "dkimEnabled": false,
      "mailFromEnabled": false,
      "dmarcEnabled": false,
      "dnsRecords": {
        "ownership": {
          "name": "_autosend-verify.example.com",
          "value": "autosend-verify-d3b3f3481f3541b1b1d96e401ad89c91",
          "type": "TXT",
          "purpose": "Domain ownership verification"
        },
        "dkim": {
          "name": "autosend._domainkey.example.com",
          "value": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ...",
          "type": "TXT",
          "purpose": "DKIM authentication"
        },
        "mailFrom": [
          {
            "name": "asend.example.com",
            "value": "feedback-smtp.us-east-1.amazonses.com",
            "type": "MX",
            "purpose": "Mail-from domain",
            "priority": 10
          },
          {
            "name": "asend.example.com",
            "value": "v=spf1 include:amazonses.com ~all",
            "type": "TXT",
            "purpose": "SPF record for mail-from domain"
          }
        ],
        "dmarc": {
          "name": "_dmarc.example.com",
          "value": "v=DMARC1; p=none;",
          "type": "TXT",
          "purpose": "DMARC policy"
        }
      },
      "createdAt": "2026-03-19T08:00:00.000Z",
      "lastCheckedAt": "2026-03-19T08:00:00.000Z",
      "regionKey": "us-east-1",
      "verificationInProgress": false
    }
  }
  ```
</ResponseExample>

### Authorizations

<ParamField path="Authorization" type="string | header" required>
  Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key.
</ParamField>

#### Body

<ParamField body="domain" type="string" required>
  A valid domain name to add (e.g. `example.com` or `mail.example.com`). Must not include a protocol (`http://`), a path, or a trailing slash. Maximum 253 characters.
</ParamField>

<ParamField body="regionKey" type="string">
  The AutoSend region key where your email service will be configured for this domain (e.g. `us-east-1`, `ap-south-1`, `us-east-2`). If omitted, the project's primary region is used.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created domain object. The initial `verificationStatus` is always `PENDING_CONFIGURATION`. Configure the required DNS records in your DNS provider and then call `POST /domains/{domainId}/verify` to start verification.

  <Expandable title="Domain object">
    <ResponseField name="id" type="string">
      Unique identifier for the domain (id). Use this as `domainId` in subsequent requests.
    </ResponseField>

    <ResponseField name="domainName" type="string">
      The domain name that was added.
    </ResponseField>

    <ResponseField name="verificationStatus" type="string">
      Always `PENDING_CONFIGURATION` on creation.
    </ResponseField>

    <ResponseField name="ownershipVerified" type="boolean">
      Always `false` on creation.
    </ResponseField>

    <ResponseField name="dkimEnabled" type="boolean">
      Always `false` on creation.
    </ResponseField>

    <ResponseField name="mailFromEnabled" type="boolean">
      Always `false` on creation.
    </ResponseField>

    <ResponseField name="dmarcEnabled" type="boolean">
      Always `false` on creation.
    </ResponseField>

    <ResponseField name="dnsRecords" type="object">
      DNS records to configure in your DNS provider before calling verify.

      <Expandable title="DNS Records object">
        <ResponseField name="ownership" type="object">
          TXT record for domain ownership verification. Contains `name`, `value`, `type`, and `purpose` fields.
        </ResponseField>

        <ResponseField name="dkim" type="object">
          TXT record for DKIM authentication. Contains `name`, `value`, `type`, and `purpose` fields.
        </ResponseField>

        <ResponseField name="mailFrom" type="array">
          Array of MX and TXT records for the MAIL FROM domain. Each record contains `name`, `value`, `type`, `purpose`, and optionally `priority` fields.
        </ResponseField>

        <ResponseField name="dmarc" type="object">
          TXT record for DMARC policy. Contains `name`, `value`, `type`, and `purpose` fields.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the domain was added.
    </ResponseField>

    <ResponseField name="lastCheckedAt" type="string">
      ISO 8601 timestamp of the last DNS verification check.
    </ResponseField>

    <ResponseField name="regionKey" type="string">
      The region key where the domain is configured (e.g. `us-east-1`).
    </ResponseField>

    <ResponseField name="verificationInProgress" type="boolean">
      Whether a DNS verification check is currently in progress. Always `false` on creation.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Errors

<ResponseField name="400" type="object">
  Returned when the `domain` field is missing, empty, exceeds 253 characters, or is not a valid domain name (e.g. includes a protocol or path).
</ResponseField>

<ResponseField name="409" type="object">
  Returned when the domain has already been added to this project.
</ResponseField>


## OpenAPI

````yaml POST /domains
openapi: 3.1.0
info:
  title: Autosend Domains API
  description: >-
    Manage your domains associated with your Autosend project. Domains are used
    to send email via AutoSend. After adding a domain you must configure DNS
    records and trigger verification before it can be used for sending.
  version: 1.0.0
servers:
  - url: https://api.autosend.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Domains
    description: Manage AutoSend domains for your Autosend project.
paths:
  /domains:
    post:
      tags:
        - Domains
      summary: Add Domain
      description: >-
        Adds a new domain to the project. The domain must be a bare domain or
        subdomain (no protocol, no path). After adding the domain, configure the
        returned DNS records in your DNS provider and call the verify endpoint
        to trigger verification.
      operationId: addDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  description: >-
                    A valid domain name (e.g. example.com or mail.example.com).
                    Must not include a protocol (http://) or path. Maximum 253
                    characters.
                  example: example.com
                regionKey:
                  type: string
                  description: >-
                    AutoSend region key where your domain will be configured
                    (e.g. us-east-1). Defaults to the project's primary region
                    if omitted.
                  example: us-east-1
      responses:
        '201':
          description: Domain added successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Domain'
              example:
                success: true
                data:
                  id: 60d5ec49f1b2c72d9c8b2222
                  domain: example.com
                  verificationStatus: PENDING_CONFIGURATION
                  ownershipVerified: false
                  dkimEnabled: false
                  mailFromEnabled: false
                  dmarcEnabled: false
                  createdAt: '2026-03-19T08:00:00.000Z'
                  updatedAt: '2026-03-19T08:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Domain already exists in the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: Domain already exists
components:
  schemas:
    Domain:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the domain (id).
          example: 60d5ec49f1b2c72d9c8b1111
        domain:
          type: string
          description: The domain name.
          example: example.com
        verificationStatus:
          type: string
          enum:
            - PENDING_CONFIGURATION
            - PENDING
            - VERIFIED
          description: >-
            Overall domain verification status. `PENDING_CONFIGURATION` — DNS
            records not yet detected. `PENDING` — DNS records detected, domain
            verification in progress. `VERIFIED` — domain is fully verified and
            ready to send.
          example: VERIFIED
        ownershipVerified:
          type: boolean
          description: >-
            Whether the TXT ownership record has been verified. Once `true`,
            never reverts to `false`.
          example: true
        dkimEnabled:
          type: boolean
          description: >-
            Whether DKIM CNAME records have been verified. Once `true`, never
            reverts to `false`.
          example: true
        mailFromEnabled:
          type: boolean
          description: >-
            Whether the MAIL FROM MX/TXT records have been verified. Once
            `true`, never reverts to `false`.
          example: true
        dmarcEnabled:
          type: boolean
          description: >-
            Whether a DMARC TXT record has been detected. Once `true`, never
            reverts to `false`.
          example: false
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the domain was added.
          example: '2026-01-05T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last status update.
          example: '2026-03-10T14:20:00.000Z'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: domain must be a valid domain name
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued from the Autosend dashboard. Pass as `Authorization:
        Bearer <token>`.

````