Domains

Retrieve a list of domains

GET /domains

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/domains" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
      "name": "example.com",
      "status": "not_started",
      "created_at": "2023-04-26 20:21:26.347412+00",
      "region": "us-east-1",
      "open_tracking": true,
      "click_tracking": true,
      "capabilities": {
        "sending": "enabled",
        "receiving": "enabled"
      }
    }
  ]
}

Create a new domain

POST /domains

Body

Field	Type	Required	Description
`name`	`string`	yes	The name of the domain you want to create.
`region`	`"us-east-1" \| "eu-west-1" \| "sa-east-1" \| "ap-northeast-1"`	no	The region where emails will be sent from. Possible values are us-east-1 \| eu-west-1 \| sa-east-1 \| ap-northeast-1
`custom_return_path`	`string`	no	For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld).
`open_tracking`	`boolean`	no	Track the open rate of each email.
`click_tracking`	`boolean`	no	Track clicks within the body of each HTML email.
`tls`	`"opportunistic" \| "enforced"`	no	TLS mode. Opportunistic attempts secure connection but falls back to unencrypted. Enforced requires TLS or email won't be sent.
`capabilities`	`object`	no	Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.
`capabilities.sending`	`"enabled" \| "disabled"`	no	Enable or disable sending emails from this domain.
`capabilities.receiving`	`"enabled" \| "disabled"`	no	Enable or disable receiving emails to this domain.
`tracking_subdomain`	`string`	no	The subdomain to use for click and open tracking.

Example

curl -X POST "$SESAMESEND_URL/domains" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

Responses

Status	Description
`201`	OK

{
  "id": "string",
  "name": "string",
  "created_at": "2023-10-06 23:47:56.678+00",
  "status": "pending",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "records": [
    {
      "record": "SPF",
      "name": "string",
      "type": "MX",
      "ttl": "string",
      "status": "pending",
      "value": "string",
      "priority": 1
    }
  ],
  "region": "string",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string"
}

Retrieve a single domain

GET /domains/{domain_id}

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the domain.

Example

curl -X GET "$SESAMESEND_URL/domains/<domain_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "not_started",
  "created_at": "2023-04-26 20:21:26.347412+00",
  "region": "us-east-1",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "records": [
    {
      "record": "SPF",
      "name": "string",
      "type": "MX",
      "ttl": "string",
      "status": "pending",
      "value": "string",
      "priority": 1
    }
  ]
}

Update an existing domain

PATCH /domains/{domain_id}

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the domain.

Body

Field	Type	Required	Description
`open_tracking`	`boolean`	no	Track the open rate of each email.
`click_tracking`	`boolean`	no	Track clicks within the body of each HTML email.
`tls`	`"opportunistic" \| "enforced"`	no	enforced \| opportunistic.
`capabilities`	`object`	no	Configure the domain capabilities for sending and receiving emails. At least one capability must be enabled.
`capabilities.sending`	`"enabled" \| "disabled"`	no	Enable or disable sending emails from this domain.
`capabilities.receiving`	`"enabled" \| "disabled"`	no	Enable or disable receiving emails to this domain.
`tracking_subdomain`	`string`	no	The subdomain to use for click and open tracking.

Example

curl -X PATCH "$SESAMESEND_URL/domains/<domain_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`200`	OK

{
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "object": "domain"
}

Remove an existing domain

DELETE /domains/{domain_id}

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the domain.

Example

curl -X DELETE "$SESAMESEND_URL/domains/<domain_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "deleted": true
}

Verify an existing domain

POST /domains/{domain_id}/verify

Triggers verification of the domain's DNS records including DKIM, SPF, and the tracking CNAME (if a tracking subdomain is configured).

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the domain.

Example

curl -X POST "$SESAMESEND_URL/domains/<domain_id>/verify" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206"
}

Claim a domain

POST /domains/claim

Not yet exercised

This route exists, but it has not yet returned a 2xx response to a real request on the reference instance (see PARITY.md in the repository). Treat its behavior as unverified.

Start a claim for a domain that another team has already verified. The domain is recreated under your account with fresh DKIM keys, so the previous account's DNS records cannot be reused. Returns a TXT record to add to your DNS to prove ownership. Uses the same request body as creating a domain.

Body

Field	Type	Required	Description
`name`	`string`	yes	The name of the domain you want to claim.
`region`	`"us-east-1" \| "eu-west-1" \| "sa-east-1" \| "ap-northeast-1"`	no	The region where emails will be sent from. Possible values are us-east-1 \| eu-west-1 \| sa-east-1 \| ap-northeast-1
`custom_return_path`	`string`	no	For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld).
`open_tracking`	`boolean`	no	Track the open rate of each email.
`click_tracking`	`boolean`	no	Track clicks within the body of each HTML email.
`tracking_subdomain`	`string`	no	The subdomain to use for click and open tracking.

Example

curl -X POST "$SESAMESEND_URL/domains/claim" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

Responses

Status	Description
`200`	An identical pending claim already existed and was returned unchanged.
`201`	Claim created.

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Retrieve a domain claim

GET /domains/{domain_id}/claim

Not yet exercised

This route exists, but it has not yet returned a 2xx response to a real request on the reference instance (see PARITY.md in the repository). Treat its behavior as unverified.

Retrieve the latest claim for the placeholder domain created by the claim.

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the placeholder domain created by the claim.

Example

curl -X GET "$SESAMESEND_URL/domains/<domain_id>/claim" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Verify a domain claim

POST /domains/{domain_id}/claim/verify

Not yet exercised

This route exists, but it has not yet returned a 2xx response to a real request on the reference instance (see PARITY.md in the repository). Treat its behavior as unverified.

Trigger asynchronous DNS verification and ownership transfer for a domain claim. The claim stays pending while verification runs; poll the retrieve endpoint for status. Once completed, the transferred domain has new DKIM records that must be added to DNS and verified via the standard domain verify endpoint.

Path parameters

Name	Type	Required	Description
`domain_id`	`string`	yes	The ID of the placeholder domain created by the claim.

Example

curl -X POST "$SESAMESEND_URL/domains/<domain_id>/claim/verify" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "resend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Retrieve a list of domainsCopy Anchor Link

Create a new domainCopy Anchor Link

Retrieve a single domainCopy Anchor Link

Update an existing domainCopy Anchor Link

Remove an existing domainCopy Anchor Link

Verify an existing domainCopy Anchor Link

Claim a domainCopy Anchor Link

Retrieve a domain claimCopy Anchor Link

Verify a domain claimCopy Anchor Link

On this page

Retrieve a list of domains

Create a new domain

Retrieve a single domain

Update an existing domain

Remove an existing domain

Verify an existing domain

Claim a domain

Retrieve a domain claim

Verify a domain claim