AgentMail Docs

Appearance

Domains ​

Fresh 🌱

AgentMail REST API reference for Domains. Base URL https://api.agentmail.to/v0. Authenticate with Authorization: Bearer <API_KEY>.

Create Domain ​

POST https://api.agentmail.to/v0/domains Content-Type: application/json

CLI:

bash
agentmail domains create --domain example.com

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains:
    post:
      operationId: create
      summary: Create Domain
      description: |-
        **CLI:**
        ```bash
        agentmail domains create --domain example.com
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_domains:Domain'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ValidationErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_domains:CreateDomainRequest'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainName:
      type: string
      description: The name of the domain (e.g., `example.com`).
      title: DomainName
    type_domains:FeedbackEnabled:
      type: boolean
      description: Bounce and complaint notifications are sent to your inboxes.
      title: FeedbackEnabled
    type_domains:SubdomainsEnabled:
      type: boolean
      description: >-
        Allow inboxes on any subdomain of this domain. Adds a required wildcard
        MX

        record (`*.<domain>`) to `records`.
      title: SubdomainsEnabled
    type_domains:CreateDomainRequest:
      type: object
      properties:
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
      required:
        - domain
      title: CreateDomainRequest
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_domains:VerificationStatus:
      type: string
      enum:
        - NOT_STARTED
        - PENDING
        - INVALID
        - FAILED
        - VERIFYING
        - VERIFIED
      title: VerificationStatus
    type_domains:Status:
      $ref: '#/components/schemas/type_domains:VerificationStatus'
      description: The verification status of the domain.
      title: Status
    type_domains:RecordType:
      type: string
      enum:
        - TXT
        - CNAME
        - MX
      title: RecordType
    type_domains:RecordStatus:
      type: string
      enum:
        - MISSING
        - INVALID
        - VALID
      title: RecordStatus
    type_domains:VerificationRecord:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_domains:RecordType'
          description: The type of the DNS record.
        name:
          type: string
          description: The name or host of the record.
        value:
          type: string
          description: The value of the record.
        status:
          $ref: '#/components/schemas/type_domains:RecordStatus'
          description: The verification status of this specific record.
        priority:
          type: integer
          description: The priority of the MX record.
      required:
        - type
        - name
        - value
        - status
      title: VerificationRecord
    type_domains:ClientId:
      type: string
      description: Client ID of domain.
      title: ClientId
    type_domains:Domain:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        domain_id:
          $ref: '#/components/schemas/type_domains:DomainId'
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        status:
          $ref: '#/components/schemas/type_domains:Status'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
        records:
          type: array
          items:
            $ref: '#/components/schemas/type_domains:VerificationRecord'
          description: |-
            A list of DNS records required to verify the domain. Includes a
            wildcard MX record (`*.<domain>`) when `subdomains_enabled` is true.
        client_id:
          $ref: '#/components/schemas/type_domains:ClientId'
        updated_at:
          type: string
          format: date-time
          description: Time at which the domain was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which the domain was created.
      required:
        - domain_id
        - domain
        - status
        - feedback_enabled
        - subdomains_enabled
        - records
        - updated_at
        - created_at
      title: Domain
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        errors:
          description: Validation errors.
      required:
        - name
        - errors
      title: ValidationErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

Request

json
{
  "domain": "domain"
}

Response

json
{
  "domain_id": "domain_id",
  "domain": "domain",
  "status": "NOT_STARTED",
  "feedback_enabled": true,
  "subdomains_enabled": true,
  "records": [
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    },
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    }
  ],
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "pod_id": "pod_id",
  "client_id": "client_id"
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.create({
        domain: "domain",
    });
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.create(
    domain="domain",
)
go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains"

	payload := strings.NewReader("{\n  \"domain\": \"domain\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <api_key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"domain\": \"domain\"\n}"

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/domains")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain\": \"domain\"\n}")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentmail.to/v0/domains', [
  'body' => '{
  "domain": "domain"
}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"domain\": \"domain\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = ["domain": "domain"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Get Domain ​

GET https://api.agentmail.to/v0/domains/{domain_id}

CLI:

bash
agentmail domains get --domain-id <domain_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains/{domain_id}:
    get:
      operationId: get
      summary: Get Domain
      description: |-
        **CLI:**
        ```bash
        agentmail domains get --domain-id <domain_id>
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_domains:DomainId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_domains:Domain'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_domains:DomainName:
      type: string
      description: The name of the domain (e.g., `example.com`).
      title: DomainName
    type_domains:VerificationStatus:
      type: string
      enum:
        - NOT_STARTED
        - PENDING
        - INVALID
        - FAILED
        - VERIFYING
        - VERIFIED
      title: VerificationStatus
    type_domains:Status:
      $ref: '#/components/schemas/type_domains:VerificationStatus'
      description: The verification status of the domain.
      title: Status
    type_domains:FeedbackEnabled:
      type: boolean
      description: Bounce and complaint notifications are sent to your inboxes.
      title: FeedbackEnabled
    type_domains:SubdomainsEnabled:
      type: boolean
      description: >-
        Allow inboxes on any subdomain of this domain. Adds a required wildcard
        MX

        record (`*.<domain>`) to `records`.
      title: SubdomainsEnabled
    type_domains:RecordType:
      type: string
      enum:
        - TXT
        - CNAME
        - MX
      title: RecordType
    type_domains:RecordStatus:
      type: string
      enum:
        - MISSING
        - INVALID
        - VALID
      title: RecordStatus
    type_domains:VerificationRecord:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_domains:RecordType'
          description: The type of the DNS record.
        name:
          type: string
          description: The name or host of the record.
        value:
          type: string
          description: The value of the record.
        status:
          $ref: '#/components/schemas/type_domains:RecordStatus'
          description: The verification status of this specific record.
        priority:
          type: integer
          description: The priority of the MX record.
      required:
        - type
        - name
        - value
        - status
      title: VerificationRecord
    type_domains:ClientId:
      type: string
      description: Client ID of domain.
      title: ClientId
    type_domains:Domain:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        domain_id:
          $ref: '#/components/schemas/type_domains:DomainId'
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        status:
          $ref: '#/components/schemas/type_domains:Status'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
        records:
          type: array
          items:
            $ref: '#/components/schemas/type_domains:VerificationRecord'
          description: |-
            A list of DNS records required to verify the domain. Includes a
            wildcard MX record (`*.<domain>`) when `subdomains_enabled` is true.
        client_id:
          $ref: '#/components/schemas/type_domains:ClientId'
        updated_at:
          type: string
          format: date-time
          description: Time at which the domain was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which the domain was created.
      required:
        - domain_id
        - domain
        - status
        - feedback_enabled
        - subdomains_enabled
        - records
        - updated_at
        - created_at
      title: Domain
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

Response

json
{
  "domain_id": "domain_id",
  "domain": "domain",
  "status": "NOT_STARTED",
  "feedback_enabled": true,
  "subdomains_enabled": true,
  "records": [
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    },
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    }
  ],
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "pod_id": "pod_id",
  "client_id": "client_id"
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.get("domain_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.get(
    domain_id="domain_id",
)
go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains/domain_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains/domain_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/domains/domain_id")
  .header("Authorization", "Bearer <api_key>")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/domains/domain_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains/domain_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains/domain_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

List Domains ​

GET https://api.agentmail.to/v0/domains

CLI:

bash
agentmail domains list

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains:
    get:
      operationId: list
      summary: List Domains
      description: |-
        **CLI:**
        ```bash
        agentmail domains list
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Limit'
        - name: page_token
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:PageToken'
        - name: ascending
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Ascending'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_domains:ListDomainsResponse'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_:Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_:PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    type_:Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_domains:DomainName:
      type: string
      description: The name of the domain (e.g., `example.com`).
      title: DomainName
    type_domains:FeedbackEnabled:
      type: boolean
      description: Bounce and complaint notifications are sent to your inboxes.
      title: FeedbackEnabled
    type_domains:SubdomainsEnabled:
      type: boolean
      description: >-
        Allow inboxes on any subdomain of this domain. Adds a required wildcard
        MX

        record (`*.<domain>`) to `records`.
      title: SubdomainsEnabled
    type_domains:ClientId:
      type: string
      description: Client ID of domain.
      title: ClientId
    type_domains:DomainItem:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        domain_id:
          $ref: '#/components/schemas/type_domains:DomainId'
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
        client_id:
          $ref: '#/components/schemas/type_domains:ClientId'
        updated_at:
          type: string
          format: date-time
          description: Time at which the domain was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which the domain was created.
      required:
        - domain_id
        - domain
        - feedback_enabled
        - subdomains_enabled
        - updated_at
        - created_at
      title: DomainItem
    type_domains:ListDomainsResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        domains:
          type: array
          items:
            $ref: '#/components/schemas/type_domains:DomainItem'
          description: Ordered by `created_at` descending.
      required:
        - count
        - domains
      title: ListDomainsResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

Response

json
{
  "count": 1,
  "domains": [
    {
      "domain_id": "domain_id",
      "domain": "domain",
      "feedback_enabled": true,
      "subdomains_enabled": true,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "pod_id": "pod_id",
      "client_id": "client_id"
    },
    {
      "domain_id": "domain_id",
      "domain": "domain",
      "feedback_enabled": true,
      "subdomains_enabled": true,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "pod_id": "pod_id",
      "client_id": "client_id"
    }
  ],
  "limit": 1,
  "next_page_token": "next_page_token"
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.list({});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.list()
go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/domains")
  .header("Authorization", "Bearer <api_key>")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/domains', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Update Domain ​

PATCH https://api.agentmail.to/v0/domains/{domain_id} Content-Type: application/json

CLI:

bash
agentmail domains update --domain-id <domain_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains/{domain_id}:
    patch:
      operationId: update
      summary: Update Domain
      description: |-
        **CLI:**
        ```bash
        agentmail domains update --domain-id <domain_id>
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_domains:DomainId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_domains:Domain'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_domains:UpdateDomainRequest'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_domains:FeedbackEnabled:
      type: boolean
      description: Bounce and complaint notifications are sent to your inboxes.
      title: FeedbackEnabled
    type_domains:SubdomainsEnabled:
      type: boolean
      description: >-
        Allow inboxes on any subdomain of this domain. Adds a required wildcard
        MX

        record (`*.<domain>`) to `records`.
      title: SubdomainsEnabled
    type_domains:UpdateDomainRequest:
      type: object
      properties:
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
      description: >-
        Provide at least one of `feedback_enabled` or `subdomains_enabled`.
        Omitted

        fields are left unchanged; an empty body is rejected. Enabling

        `subdomains_enabled` on a verified domain returns it to `PENDING` until
        the

        newly-required wildcard MX record (`*.<domain>`) is published and
        verified.
      title: UpdateDomainRequest
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_domains:DomainName:
      type: string
      description: The name of the domain (e.g., `example.com`).
      title: DomainName
    type_domains:VerificationStatus:
      type: string
      enum:
        - NOT_STARTED
        - PENDING
        - INVALID
        - FAILED
        - VERIFYING
        - VERIFIED
      title: VerificationStatus
    type_domains:Status:
      $ref: '#/components/schemas/type_domains:VerificationStatus'
      description: The verification status of the domain.
      title: Status
    type_domains:RecordType:
      type: string
      enum:
        - TXT
        - CNAME
        - MX
      title: RecordType
    type_domains:RecordStatus:
      type: string
      enum:
        - MISSING
        - INVALID
        - VALID
      title: RecordStatus
    type_domains:VerificationRecord:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_domains:RecordType'
          description: The type of the DNS record.
        name:
          type: string
          description: The name or host of the record.
        value:
          type: string
          description: The value of the record.
        status:
          $ref: '#/components/schemas/type_domains:RecordStatus'
          description: The verification status of this specific record.
        priority:
          type: integer
          description: The priority of the MX record.
      required:
        - type
        - name
        - value
        - status
      title: VerificationRecord
    type_domains:ClientId:
      type: string
      description: Client ID of domain.
      title: ClientId
    type_domains:Domain:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        domain_id:
          $ref: '#/components/schemas/type_domains:DomainId'
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        status:
          $ref: '#/components/schemas/type_domains:Status'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
        records:
          type: array
          items:
            $ref: '#/components/schemas/type_domains:VerificationRecord'
          description: |-
            A list of DNS records required to verify the domain. Includes a
            wildcard MX record (`*.<domain>`) when `subdomains_enabled` is true.
        client_id:
          $ref: '#/components/schemas/type_domains:ClientId'
        updated_at:
          type: string
          format: date-time
          description: Time at which the domain was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which the domain was created.
      required:
        - domain_id
        - domain
        - status
        - feedback_enabled
        - subdomains_enabled
        - records
        - updated_at
        - created_at
      title: Domain
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

Request

json
{}

Response

json
{
  "domain_id": "domain_id",
  "domain": "domain",
  "status": "NOT_STARTED",
  "feedback_enabled": true,
  "subdomains_enabled": true,
  "records": [
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    },
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1
    }
  ],
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "pod_id": "pod_id",
  "client_id": "client_id"
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.update("domain_id", {});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.update(
    domain_id="domain_id",
)
go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains/domain_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <api_key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains/domain_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.agentmail.to/v0/domains/domain_id")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.agentmail.to/v0/domains/domain_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains/domain_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains/domain_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Verify Domain ​

POST https://api.agentmail.to/v0/domains/{domain_id}/verify

CLI:

bash
agentmail domains verify --domain-id <domain_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains/{domain_id}/verify:
    post:
      operationId: verify
      summary: Verify Domain
      description: |-
        **CLI:**
        ```bash
        agentmail domains verify --domain-id <domain_id>
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_domains:DomainId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.verify("domain_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.verify(
    domain_id="domain_id",
)
go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains/domain_id/verify"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains/domain_id/verify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/domains/domain_id/verify")
  .header("Authorization", "Bearer <api_key>")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentmail.to/v0/domains/domain_id/verify', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains/domain_id/verify");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains/domain_id/verify")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Get Zone File ​

GET https://api.agentmail.to/v0/domains/{domain_id}/zone-file

CLI:

bash
agentmail domains get-zone-file --domain-id <domain_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains/{domain_id}/zone-file:
    get:
      operationId: get-zone-file
      summary: Get Zone File
      description: |-
        **CLI:**
        ```bash
        agentmail domains get-zone-file --domain-id <domain_id>
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_domains:DomainId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.getZoneFile(":domain_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.get_zone_file(
    domain_id=":domain_id",
)
go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file")
  .header("Authorization", "Bearer <api_key>")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains/%3Adomain_id/zone-file")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Delete Domain ​

DELETE https://api.agentmail.to/v0/domains/{domain_id}

CLI:

bash
agentmail domains delete --domain-id <domain_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/domains/{domain_id}:
    delete:
      operationId: delete
      summary: Delete Domain
      description: |-
        **CLI:**
        ```bash
        agentmail domains delete --domain-id <domain_id>
        ```
      tags:
        - subpackage_domains
      parameters:
        - name: domain_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_domains:DomainId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
servers:
  - url: https://api.agentmail.to
    description: prod
  - url: https://x402.api.agentmail.to
    description: prod-x402
  - url: https://mpp.api.agentmail.to
    description: prod-mpp
  - url: https://api.agentmail.eu
    description: eu-prod
components:
  schemas:
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples ​

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.domains.delete("domain_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.domains.delete(
    domain_id="domain_id",
)
go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/domains/domain_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/domains/domain_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.delete("https://api.agentmail.to/v0/domains/domain_id")
  .header("Authorization", "Bearer <api_key>")
  .asString();
php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.agentmail.to/v0/domains/domain_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/domains/domain_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/domains/domain_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()