Email Domain

Manage your custom email domain for sending branded transactional emails (booking confirmations, reminders, etc.) from your own domain instead of the default EquipDash address.

Each supplier can have one custom email domain. The domain must be verified via DNS (DKIM) before it can be used.

Endpoints

Method	Endpoint	Description	Scope Required
GET	/v1/email-domain	Get email domain configuration	settings:read
POST	/v1/email-domain	Create and verify a new email domain	settings:write
POST	/v1/email-domain/check-status	Refresh verification status	settings:write
POST	/v1/email-domain/retry	Start verification again after it failed	settings:write
DELETE	/v1/email-domain	Remove the email domain	settings:write
PATCH	/v1/email-domain/toggle	Enable or disable the email domain	settings:write

---

Email Domain Object

{
  "id": 1,
  "domain": "example.com",
  "from_email": "bookings@example.com",
  "from_name": "My Business",
  "verification_status": "pending",
  "dkim_records": [
    {
      "type": "CNAME",
      "name": "abc123._domainkey.example.com",
      "value": "abc123.dkim.amazonses.com"
    },
    {
      "type": "CNAME",
      "name": "def456._domainkey.example.com",
      "value": "def456.dkim.amazonses.com"
    },
    {
      "type": "CNAME",
      "name": "ghi789._domainkey.example.com",
      "value": "ghi789.dkim.amazonses.com"
    }
  ],
  "enabled": true,
  "verified_at": null,
  "last_checked_at": null,
  "created_at": "2026-03-25T12:00:00+00:00",
  "updated_at": "2026-03-25T12:00:00+00:00"
}

Fields

Field	Type	Description
id	integer	Unique identifier
domain	string	The custom domain (e.g., example.com)
from_email	string	The sender email address (must use the custom domain)
from_name	string	The sender display name
verification_status	string	Current verification status (see below)
dkim_records	array	DKIM CNAME records to add to your DNS
enabled	boolean	Whether the custom domain is actively used for sending
verified_at	string|null	ISO 8601 datetime when domain was verified
last_checked_at	string|null	ISO 8601 datetime of last verification check
created_at	string	ISO 8601 datetime
updated_at	string	ISO 8601 datetime

Verification Statuses

Status	Description
pending	Domain created, waiting for DNS records to be configured and verified
verified	DNS records confirmed, domain is ready for sending
failed	DNS verification failed (records not found or incorrect)
revoked	Domain was previously verified but verification has been revoked

DKIM Record Object

Field	Type	Description
type	string	Always CNAME
name	string	The DNS record name to create
value	string	The DNS record value to point to

---

Get Email Domain

Retrieve the current email domain configuration.

GET /v1/email-domain

Authentication

Requires an API key with the settings:read scope.

Example Request

curl -X GET "https://app.equipdash.com/api/v1/email-domain" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Response

Success (200 OK)

{
  "data": {
    "id": 1,
    "domain": "example.com",
    "from_email": "bookings@example.com",
    "from_name": "My Business",
    "verification_status": "verified",
    "dkim_records": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.example.com",
        "value": "abc123.dkim.amazonses.com"
      }
    ],
    "enabled": true,
    "verified_at": "2026-03-25T12:00:00+00:00",
    "last_checked_at": "2026-03-25T12:00:00+00:00",
    "created_at": "2026-03-25T10:00:00+00:00",
    "updated_at": "2026-03-25T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T12:00:00+00:00"
  }
}

Not Found (404)

Returned when no email domain has been configured.

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested email domain could not be found."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T12:00:00+00:00"
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:read scope
404	resource_not_found	No email domain configured

---

Create Email Domain

Create a new custom email domain and initiate DNS verification. This returns the DKIM records that must be added to your DNS configuration.

POST /v1/email-domain

Authentication

Requires an API key with the settings:write scope.

Request Body

Field	Type	Required	Description
domain	string	Yes	The domain to verify (e.g., example.com). Must be a valid domain format.
from_email	string	Yes	The sender email address. Must use the specified domain.
from_name	string	Yes	The sender display name (max 255 characters).

Example Request

curl -X POST "https://app.equipdash.com/api/v1/email-domain" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "from_email": "bookings@example.com",
    "from_name": "My Business"
  }'

Response

Success (201 Created)

{
  "data": {
    "id": 1,
    "domain": "example.com",
    "from_email": "bookings@example.com",
    "from_name": "My Business",
    "verification_status": "pending",
    "dkim_records": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.example.com",
        "value": "abc123.dkim.amazonses.com"
      },
      {
        "type": "CNAME",
        "name": "def456._domainkey.example.com",
        "value": "def456.dkim.amazonses.com"
      },
      {
        "type": "CNAME",
        "name": "ghi789._domainkey.example.com",
        "value": "ghi789.dkim.amazonses.com"
      }
    ],
    "enabled": true,
    "verified_at": null,
    "last_checked_at": null,
    "created_at": "2026-03-25T12:00:00+00:00",
    "updated_at": "2026-03-25T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T12:00:00+00:00"
  }
}

Add DKIM Records to Your DNS

After creating the email domain, you must add the returned dkim_records as CNAME records in your DNS provider. Verification typically takes a few minutes but can take up to 72 hours for DNS propagation. Use the Check Verification Status endpoint to poll for updates.

Validation Rules

• domain must be a valid domain format (e.g., example.com, mail.example.com)
• from_email must be a valid email address
• from_email must use the specified domain (e.g., if domain is example.com, email must end with @example.com)

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:write scope
422	validation_error	Invalid request data
422	verification_error	Domain verification could not be initiated

Validation Error Example

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": {
      "from_email": ["The email address must use the specified domain."]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T12:00:00+00:00"
  }
}

---

Check Verification Status

Refresh the DNS verification status for the configured email domain. Use this endpoint to poll for verification completion after adding DKIM records to your DNS.

POST /v1/email-domain/check-status

Authentication

Requires an API key with the settings:write scope.

Example Request

curl -X POST "https://app.equipdash.com/api/v1/email-domain/check-status" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Response

Success (200 OK)

Returns the email domain with the updated verification status.

{
  "data": {
    "id": 1,
    "domain": "example.com",
    "from_email": "bookings@example.com",
    "from_name": "My Business",
    "verification_status": "verified",
    "dkim_records": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.example.com",
        "value": "abc123.dkim.amazonses.com"
      }
    ],
    "enabled": true,
    "verified_at": "2026-03-25T14:30:00+00:00",
    "last_checked_at": "2026-03-25T14:30:00+00:00",
    "created_at": "2026-03-25T12:00:00+00:00",
    "updated_at": "2026-03-25T14:30:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T14:30:00+00:00"
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:write scope
422	check_status_error	Verification check failed (e.g., no domain configured)

---

Retry Verification

Starts the DNS check again for a domain whose verification_status is failed or revoked. Use this after adding or fixing the DKIM records. check-status only reads the current status and does not restart a failed check.

POST /v1/email-domain/retry

Authentication

Requires an API key with the settings:write scope.

Example Request

curl -X POST "https://app.equipdash.com/api/v1/email-domain/retry" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Response

Success (200 OK)

Returns the email domain with verification_status set to pending. Read dkim_records from the response: if the original records could not be reused, new ones are issued and the old ones no longer work.

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:write scope
422	retry_error	No domain configured, the domain is already verified, or the check could not be started

---

Remove Email Domain

Remove the custom email domain configuration. After removal, all transactional emails will be sent from the default EquipDash address.

DELETE /v1/email-domain

Authentication

Requires an API key with the settings:write scope.

Example Request

curl -X DELETE "https://app.equipdash.com/api/v1/email-domain" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Response

Success (204 No Content)

Returns an empty response body.

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:write scope
422	remove_error	Domain removal failed (e.g., no domain configured)

Notes

• This action cannot be undone. You will need to reconfigure and re-verify the domain if you want to use it again.
• Any DKIM DNS records can be safely removed from your DNS after deletion.

---

Toggle Email Domain

Enable or disable the custom email domain without removing it. When disabled, emails are sent from the default EquipDash address. The domain must be verified before it can be enabled.

PATCH /v1/email-domain/toggle

Authentication

Requires an API key with the settings:write scope.

Request Body

Field	Type	Required	Description
enabled	boolean	Yes	true to enable, false to disable

Example Request

curl -X PATCH "https://app.equipdash.com/api/v1/email-domain/toggle" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response

Success (200 OK)

Returns the email domain with the updated enabled status.

{
  "data": {
    "id": 1,
    "domain": "example.com",
    "from_email": "bookings@example.com",
    "from_name": "My Business",
    "verification_status": "verified",
    "dkim_records": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.example.com",
        "value": "abc123.dkim.amazonses.com"
      }
    ],
    "enabled": false,
    "verified_at": "2026-03-25T14:30:00+00:00",
    "last_checked_at": "2026-03-25T14:30:00+00:00",
    "created_at": "2026-03-25T12:00:00+00:00",
    "updated_at": "2026-03-25T15:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-25T15:00:00+00:00"
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks settings:write scope
422	validation_error	Invalid request data
422	toggle_error	Toggle failed (e.g., no domain configured, or domain not verified)

---

Verification Workflow

Setting up a custom email domain follows this workflow:

1. Create the email domain via POST /v1/email-domain with your domain, sender email, and sender name
2. Add DNS records - take the returned dkim_records and create CNAME records in your DNS provider
3. Wait for propagation - DNS changes can take minutes to 72 hours to propagate
4. Check status - poll POST /v1/email-domain/check-status until verification_status changes from pending to verified
5. Send emails - once verified and enabled, all transactional emails use your custom domain

If the records are not found within 72 hours, verification_status becomes failed and the account's admins get an email. Fix the records, then call POST /v1/email-domain/retry.

Create domain (POST)  →  Add DKIM to DNS  →  Poll status  →  Verified!
     ↓                                          ↓
  "pending"                                 "verified"

Common Use Cases

Setting Up a Custom Domain

# Step 1: Create the domain
curl -X POST "https://app.equipdash.com/api/v1/email-domain" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "myshop.com",
    "from_email": "rentals@myshop.com",
    "from_name": "My Rental Shop"
  }'

# Step 2: Add the returned DKIM CNAME records to your DNS

# Step 3: Check verification status
curl -X POST "https://app.equipdash.com/api/v1/email-domain/check-status" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Temporarily Disabling Custom Domain

curl -X PATCH "https://app.equipdash.com/api/v1/email-domain/toggle" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Related Resources

• Settings Overview - Business settings and configuration