Domains API

The Domains API allows you to add and manage custom domains for sending emails from your organization's brand.

Prerequisites

Custom domains require one of the following:

• A plan of $250/month or higher (domains included)
• The domains add-on ($15/month)

List Domains

Get all domains connected to your organization.

GET /domains

Response:

{
  "success": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "example.com",
      "status": "active",
      "type": "imported",
      "dns_configured": true,
      "mx_verified": true,
      "spf_verified": true,
      "dkim_verified": true,
      "verified_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Domain Status

Add Domain

Connect a new domain to your organization.

POST /domains

Request Body:

{
  "domain": "acme.com"
}

Response:

{
  "success": true,
  "data": {
    "id": "dom_xyz789",
    "domain": "acme.com",
    "status": "pending",
    "dns_records": [
      {
        "type": "MX",
        "name": "acme.com",
        "value": "mx.vastal.com",
        "priority": 10
      },
      {
        "type": "TXT",
        "name": "acme.com",
        "value": "v=spf1 include:_spf.vastal.com ~all"
      },
      {
        "type": "CNAME",
        "name": "vsm1._domainkey.acme.com",
        "value": "vsm1.dkim.vastal.com"
      },
      {
        "type": "CNAME",
        "name": "vsm2._domainkey.acme.com",
        "value": "vsm2.dkim.vastal.com"
      }
    ]
  }
}

Required DNS Records

After adding a domain, you need to configure these DNS records:

MX Record (for receiving email)

SPF Record (for sending authentication)

DKIM Records (for email signing)

Verify Domain

Check if DNS records are properly configured.

GET /domains/{domain_id}/verify

Response (Success):

{
  "success": true,
  "data": {
    "mx_verified": true,
    "spf_verified": true,
    "dkim_verified": true,
    "all_verified": true,
    "status": "active"
  }
}

Response (Pending):

{
  "success": true,
  "data": {
    "mx_verified": true,
    "spf_verified": false,
    "dkim_verified": false,
    "all_verified": false,
    "status": "pending",
    "issues": [
      "SPF record not found",
      "DKIM CNAME vsm1._domainkey not found"
    ]
  }
}

Remove Domain

Disconnect a domain from your organization.

DELETE /domains/{domain_id}

Warning: Removing a domain will disable email sending from that domain immediately.

Email Addresses

Once a domain is verified, you can create email addresses on it.

List Email Addresses

GET /domains/{domain_id}/emails

Response:

{
  "success": true,
  "data": [
    {
      "id": "email_001",
      "address": "hello@acme.com",
      "is_primary": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "email_002",
      "address": "support@acme.com",
      "is_primary": false,
      "created_at": "2024-01-16T09:00:00Z"
    }
  ]
}

Create Email Address

POST /domains/{domain_id}/emails

Request Body:

{
  "local_part": "sales",
  "is_primary": false
}

This creates sales@yourdomain.com.

DNS Propagation

DNS changes can take up to 48 hours to propagate globally. During this time:

1. The domain status will remain pending
2. Verification requests may return partial results
3. Email sending will not be available

We recommend verifying your domain periodically until all records show as verified.

Troubleshooting

MX Record Not Found

• Ensure you've added the MX record at the root of your domain
• Check that no conflicting MX records exist
• Wait for DNS propagation (up to 48 hours)

SPF Record Issues

• Only one SPF record is allowed per domain
• If you have existing SPF records, merge them: v=spf1 include:_spf.vastal.com include:other.provider.com ~all

DKIM Not Verifying

• DKIM uses CNAME records, not TXT
• Ensure both vsm1._domainkey and vsm2._domainkey are configured
• Check for typos in the CNAME target values