Domain Management Guide

This guide provides comprehensive documentation for managing sending domains in EDITH. Proper domain configuration is essential for email deliverability and authentication.

Overview

Before you can send emails through EDITH, you must:

Add a sending domain - Register your domain with the platform
Configure DNS records - Add DKIM and SPF records to authenticate emails
Verify the domain - Confirm DNS records are properly configured

Add a New Domain

Endpoint

POST /v1/domain/add

Purpose

Creates a new sending domain and generates the required DNS records (DKIM, SPF, CNAME) that you'll need to add to your domain's DNS settings.

Request Body

Field	Type	Required	Description
`domain`	string	✅ Yes	The domain name you want to use for sending emails. This should be your verified domain (e.g., `mail.yourcompany.com`). Using a subdomain is recommended to protect your root domain reputation.
`custom_args`	object	No	Custom key-value pairs for your internal tracking or categorization. These are stored with the domain but not used by EDITH internally.
`is_tenant_domain`	boolean	No	Set to `true` if this domain is the primary domain for a tenant/organization. Default: `false`
`is_tenant_subdomain`	boolean	No	Set to `true` if this is a subdomain of a tenant's primary domain. Default: `false`
`selector`	string	No	Custom DKIM selector. If not provided, a default selector will be generated. DKIM selectors allow you to have multiple DKIM keys for the same domain.
`ips`	string[]	No	List of dedicated IP addresses to associate with this domain. Only applicable for accounts with dedicated IPs. Format: `["192.168.1.1", "192.168.1.2"]`
`shared_with_subaccounts`	boolean	No	When `true`, subaccounts under your organization can use this domain for sending. Default: `false`

Example Request

curl -X POST https://api.edith.example.com/v1/domain/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mail.yourcompany.com",
    "custom_args": {
      "purpose": "transactional",
      "team": "engineering"
    },
    "shared_with_subaccounts": true
  }'

Response

{
  "success": true,
  "message": "Domain added successfully",
  "mailer_id": "domain_01JC3BBW8S9YGX2VNKG5MD7BTA",
  "verified": false,
  "is_tenant_domain": false,
  "sending_records": {
    "dkim": {
      "type": "TXT",
      "key": "scph1234._domainkey.mail.yourcompany.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqG...",
      "verified": false
    },
    "spf": {
      "type": "TXT",
      "key": "mail.yourcompany.com",
      "value": "v=spf1 include:spf.edith.example.com ~all",
      "verified": false
    }
  },
  "receiving_records": {
    "cname": {
      "type": "CNAME",
      "key": "mail.yourcompany.com",
      "value": "edith.sparrowmailer.com",
      "verified": false
    }
  }
}

Understanding DNS Records

DKIM Record

Domain Keys Identified Mail - Cryptographically signs your emails to prove they originated from your domain.

Field	Description
`key`	Add this as a TXT record name in your DNS. The format is `selector._domainkey.yourdomain.com`
`value`	The public key that receiving mail servers use to verify your email signatures

SPF Record

Sender Policy Framework - Specifies which mail servers are authorized to send emails on behalf of your domain.

Field	Description
`key`	Your domain name where the TXT record should be added
`value`	The SPF policy. The `include:` directive authorizes EDITH's servers to send on your behalf

CNAME Record (for receiving)

Required if you want to receive emails on this domain through EDITH.

Verify a Domain

Endpoint

PUT /v1/domain/verify/{domain}

Purpose

After adding DNS records to your domain, call this endpoint to verify the configuration. EDITH will check that:

DKIM records are correctly configured
SPF records include EDITH's mail servers
CNAME records point to EDITH (if applicable)

Path Parameters

Parameter	Type	Required	Description
`domain`	string	✅ Yes	The domain name to verify (must match the domain you added)

Example Request

curl -X PUT https://api.edith.example.com/v1/domain/verify/mail.yourcompany.com \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

{
  "success": true,
  "message": "Domain verified successfully",
  "verified": true,
  "records": {
    "dkim": {
      "type": "TXT",
      "key": "scph1234._domainkey.mail.yourcompany.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqG...",
      "verified": true
    },
    "spf": {
      "type": "TXT",
      "key": "mail.yourcompany.com",
      "value": "v=spf1 include:spf.edith.example.com ~all",
      "verified": true
    }
  }
}

Verification Failure Response

{
  "success": false,
  "error": "Domain verification failed",
  "records": {
    "dkim": {
      "verified": false,
      "error": "DKIM record not found or incorrect"
    },
    "spf": {
      "verified": true
    }
  }
}

Troubleshooting Verification Issues

Issue	Cause	Solution
DKIM not found	DNS record not added or not propagated	Wait 15-30 minutes for DNS propagation, then retry
DKIM mismatch	Incorrect record value copied	Verify you copied the entire DKIM value including the `v=DKIM1; k=rsa; p=` prefix
SPF not found	TXT record not added	Add the SPF TXT record to your domain
SPF invalid	Missing include directive	Ensure your SPF record includes `include:spf.edith.example.com`

Get Domain Details

Endpoint

GET /v1/domain/{domain}

Purpose

Retrieves complete information about a domain including:

Current verification status
Associated mailer ID
All DNS records (sending and receiving)
Domain configuration settings

Path Parameters

Parameter	Type	Required	Description
`domain`	string	✅ Yes	The domain name to retrieve

Example Request

curl -X GET https://api.edith.example.com/v1/domain/mail.yourcompany.com \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "mailer_id": "domain_01JC3BBW8S9YGX2VNKG5MD7BTA",
  "verified": true,
  "is_tenant_domain": false,
  "sending_records": {
    "dkim": {
      "type": "TXT",
      "key": "scph1234._domainkey.mail.yourcompany.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqG...",
      "verified": true
    },
    "spf": {
      "type": "TXT",
      "key": "mail.yourcompany.com",
      "value": "v=spf1 include:spf.edith.example.com ~all",
      "verified": true
    }
  },
  "receiving_records": {
    "cname": {
      "type": "CNAME",
      "key": "mail.yourcompany.com",
      "value": "edith.sparrowmailer.com",
      "verified": true
    },
    "mx": {
      "type": "MX",
      "key": "mail.yourcompany.com",
      "value": "10 mx.edith.example.com",
      "verified": true
    }
  }
}

Delete a Domain

Endpoint

DELETE /v1/domain/delete/{domain}

Purpose

Permanently removes a domain from your account.

⚠️ Warning: This action is irreversible. Before deleting:

Ensure no active email campaigns are using this domain
Update any applications using this domain's mailer_id
Consider the impact on email deliverability reputation

Path Parameters

Parameter	Type	Required	Description
`domain`	string	✅ Yes	The domain name to delete

Example Request

curl -X DELETE https://api.edith.example.com/v1/domain/delete/mail.yourcompany.com \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

{
  "success": true,
  "message": "Domain deleted successfully"
}

Error Response

{
  "success": false,
  "message": "Error while deleting domain",
  "error": "Domain has active email configurations"
}

Parent Account vs Sub Account Domain Management

EDITH supports hierarchical account structures where parent accounts can have multiple sub-accounts. Domain verification behaves differently depending on the account level.

Parent Account Path (Original Behavior)

Flow:

Parent Account → Tenant Domain (Manual Verification)
              → Subdomain (Auto Verified)

Parent Domain: Requires manual DNS verification (DKIM, SPF records)
Subdomains: ✅ Automatically verified when created under parent account
No additional verification required for subdomains

Example:

parentcompany.com (Manually verified under Parent Account)
  ↳ marketing.parentcompany.com (✅ Auto verified)
  ↳ support.parentcompany.com (✅ Auto verified)
  ↳ sales.parentcompany.com (✅ Auto verified)

Sub Account Path — Inherited Verification (NEW RULE)

⭐ Critical Rule: If the parent domain (e.g., parentcompany.com) is already verified under the Parent Account, any subdomain created under a Sub Account automatically inherits that verification status.

Benefits:

✅ No additional DNS configuration needed
✅ No email verification required
✅ Instant activation for sub-accounts
🔒 Subdomain remains exclusive to that Sub Account
🚫 Sub Account cannot access or update the parent domain

Example:

Parent Account:
  parentcompany.com ✅ Verified (via DNS)

Sub Account: Team A
  teamA.parentcompany.com → ✅ Auto-trusted (inherited verification)
  
Sub Account: Team B
  teamB.parentcompany.com → ✅ Auto-trusted (inherited verification)

Sub Account: Marketing
  marketing.parentcompany.com → ✅ Auto-trusted (inherited verification)

🔴 Exception: If the parent domain is not verified, then subdomains under Sub Accounts require manual verification, unless overridden by configuration.

How to Use This Feature

Step 1: Parent Account - Verify Parent Domain

# Parent Account verifies the root domain
POST /v1/domain/add
{
  "domain": "parentcompany.com",
  "is_tenant_domain": true
}

# Add DNS records (DKIM, SPF) and verify
PUT /v1/domain/verify/parentcompany.com

Step 2: Sub Account - Create Subdomain (Auto-Verified)

# Sub Account creates its subdomain
POST /v1/domain/add
{
  "domain": "teamA.parentcompany.com",
  "is_tenant_subdomain": true
}

# ✅ Automatically verified - no DNS setup needed!

Domain Access Rules

Account Type	Parent Domain	Subdomain	Verification
Parent Account	✅ Full access	✅ Full access	Manual DNS verification required
Sub Account	🚫 No access	✅ Full access (own subdomain only)	✅ Inherited if parent verified

Webhook Event Routing

Webhooks follow account context:

Event Origin	Webhook Destination
Sub Account Event	→ Sent to Sub Account webhook. If not present, uses Parent Account webhook
Parent Account Event	→ Sent to Parent Account webhook

Example:

Parent Account:
  - Webhook: https://parent.com/webhooks
  - Domain: parentcompany.com

Sub Account A:
  - Webhook: https://subA.com/webhooks
  - Domain: teamA.parentcompany.com
  - Events go to: https://subA.com/webhooks

Sub Account B (no webhook):
  - Domain: teamB.parentcompany.com
  - Events go to: https://parent.com/webhooks (fallback)

Best Practices for Parent/Sub Accounts

For Parent Accounts:

Verify the root domain first
Use clear domain naming conventions (e.g., team-name.domain.com)
Set up parent webhook as fallback
Document subdomain allocation for teams

For Sub Accounts:

Use descriptive subdomain names (marketing., sales., teamA.)
Verify parent domain is verified before creating subdomains
Set up dedicated webhooks for independent event handling
Keep is_tenant_subdomain: true when creating domains

Best Practices

1. Use Subdomains for Sending

Instead of using your root domain (yourcompany.com), use a subdomain like:

mail.yourcompany.com
notify.yourcompany.com
transactional.yourcompany.com

Why? This protects your root domain's reputation if deliverability issues occur.

2. Separate Transactional and Marketing Domains

Use different subdomains for different email types:

transactional.yourcompany.com - Account notifications, password resets
marketing.yourcompany.com - Newsletters, promotional content

3. Monitor Verification Status

Regularly check that your domains remain verified. DNS changes or expiring records can cause verification to fail.

4. Keep DNS Records Updated

When rotating DKIM keys or updating SPF records, always verify the domain again to ensure changes are propagated.

5. Use Custom Args for Organization

Leverage custom_args to categorize domains:

{
  "custom_args": {
    "environment": "production",
    "team": "customer-success",
    "region": "us-west"
  }
}

Common Errors

Error	Cause	Solution
`Domain already exists`	Domain was previously added	Use GET to check existing configuration
`Invalid domain format`	Domain name contains invalid characters	Use a valid domain format (e.g., `subdomain.domain.tld`)
`Domain not found`	Attempting to verify/delete non-existent domain	Add the domain first using POST /v1/domain/add
`Domain verification failed`	DNS records not configured or propagated	Wait for DNS propagation and ensure records are correct
`Unauthorized`	Invalid or expired authentication token	Refresh your authentication token

Domain Management Guide

Overview​

Add a New Domain​

Endpoint​

Purpose​

Request Body​

Example Request​

Response​

Understanding DNS Records​

DKIM Record​

SPF Record​

CNAME Record (for receiving)​

Verify a Domain​

Endpoint​

Purpose​

Path Parameters​

Example Request​

Success Response​

Verification Failure Response​

Troubleshooting Verification Issues​

Get Domain Details​

Endpoint​

Purpose​

Path Parameters​

Example Request​

Response​

Delete a Domain​

Endpoint​

Purpose​

Path Parameters​

Example Request​

Success Response​

Error Response​

Parent Account vs Sub Account Domain Management​

Parent Account Path (Original Behavior)​

Sub Account Path — Inherited Verification (NEW RULE)​

How to Use This Feature​

Domain Access Rules​

Webhook Event Routing​

Best Practices for Parent/Sub Accounts​

Best Practices​

1. Use Subdomains for Sending​

2. Separate Transactional and Marketing Domains​

3. Monitor Verification Status​

4. Keep DNS Records Updated​

5. Use Custom Args for Organization​

Common Errors​

Overview

Add a New Domain

Endpoint

Purpose

Request Body

Example Request

Response

Understanding DNS Records

DKIM Record

SPF Record

CNAME Record (for receiving)

Verify a Domain

Endpoint

Purpose

Path Parameters

Example Request

Success Response

Verification Failure Response

Troubleshooting Verification Issues

Get Domain Details

Endpoint

Purpose

Path Parameters

Example Request

Response

Delete a Domain

Endpoint

Purpose

Path Parameters

Example Request

Success Response

Error Response

Parent Account vs Sub Account Domain Management

Parent Account Path (Original Behavior)

Sub Account Path — Inherited Verification (NEW RULE)

How to Use This Feature

Domain Access Rules

Webhook Event Routing

Best Practices for Parent/Sub Accounts

Best Practices

1. Use Subdomains for Sending

2. Separate Transactional and Marketing Domains

3. Monitor Verification Status

4. Keep DNS Records Updated

5. Use Custom Args for Organization

Common Errors