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:

1. Add a sending domain - Register your domain with the platform
2. Configure DNS records - Add DKIM and SPF records to authenticate emails
3. 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.sparrowmailer.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.sparrowmailer.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.sparrowmailer.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
    }
  }
}

---

Update Domain Custom Args

Endpoint

PUT /v1/domain/custom-args/{domain}

Purpose

Replace the custom_args stored on an existing domain. Custom args are arbitrary key-value pairs kept for your own tracking or categorization — EDITH stores them and echoes them back (for example in webhook payloads) but does not interpret them.

Path Parameters

Parameter	Type	Required	Description
domain	string	✅ Yes	The domain whose custom args you want to update.

Request Body

Field	Type	Required	Description
custom_args	object	✅ Yes	Key-value pairs to store on the domain. Replaces any existing custom args.

Example Request

curl -X PUT https://api.sparrowmailer.com/v1/domain/custom-args/mail.yourcompany.com \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_args": {
      "team": "growth",
      "cost_center": "CC-1024"
    }
  }'

Success Response

{
  "success": true,
  "message": "Domain custom args updated successfully",
  "email_domain": {
    "id": 42,
    "domain": "mail.yourcompany.com",
    "mailer_id": "domain_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "sending_verified": true,
    "active": true,
    "type": "sending",
    "custom_args": {
      "team": "growth",
      "cost_center": "CC-1024"
    },
    "is_tenant_domain": false,
    "tenant_id": 7,
    "account_id": 7,
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T13:20:00Z"
  }
}

Error Response

Returns 404 when the domain does not exist for your account:

{
  "success": false,
  "error": "domain not found"
}

---

Switch the Mailer Service for a Domain

Endpoint

PUT /v1/domain/{domain}/mailer

Purpose

Switches which mailer service (for example SparkPost or Mailgun) a sending domain routes through.

Request Body

Field	Type	Required	Description
mailer_service	string	✅ Yes	The target provider. Send "" or null to reset the domain to the tenant default.

The switch is rejected unless both are true: the target provider is active for your tenant, and the domain is DNS-verified for that provider. Verify the domain against the new provider before switching.

Example Request

curl -X PUT https://api.sparrowmailer.com/v1/domain/mail.yourcompany.com/mailer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mailer_service": "mailgun"
  }'

Response

The response echoes the resolved provider, so you can confirm what the domain now uses:

{
  "success": true,
  "message": "Domain mailer service updated",
  "mailer_service": "mailgun"
}

Resetting to the tenant default returns "mailer_service": null:

{
  "success": true,
  "message": "Domain mailer service reset to tenant default",
  "mailer_service": null
}

---

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.sparrowmailer.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:

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

For Sub Accounts:

1. Use descriptive subdomain names (marketing., sales., teamA.)
2. Verify parent domain is verified before creating subdomains
3. Set up dedicated webhooks for independent event handling
4. 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