Domains

Manage domains in your organization.

List Domains

Returns a paginated list of all domains.

GET /api/v1/domains

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "example.com",
      "verified": true,
      "usageType": "sends-and-receives",
      "testEmailLocalPart": "admin",
      "lastCheckedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Example

curl -H "Authorization: Bearer ms_your_token" \
  "https://app.mailshield.app/api/v1/domains?limit=10"

---

Create Domain

Add a new domain to your organization.

POST /api/v1/domains

Request Body

Field	Type	Required	Description
domain	string	Yes	Domain name (e.g., "example.com")
usageType	string	No	How the domain is used (default: "sends-and-receives")
testEmailLocalPart	string	Conditional	Required for domains that receive email

Usage Types:

• sends-and-receives - Domain sends and receives email
• receives-only - Domain only receives email
• sends-only - Domain only sends email
• parked - Domain is parked (no email)

Response (201 Created)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "verified": false,
    "verificationToken": "abc123xyz",
    "usageType": "sends-and-receives",
    "testEmailLocalPart": "admin",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Example

curl -X POST \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "testEmailLocalPart": "admin"}' \
  https://app.mailshield.app/api/v1/domains

Errors

• 400 - Invalid domain format or missing required fields
• 403 - Domain limit reached (upgrade required)
• 409 - Domain already exists

---

Get Domain

Returns domain details with the latest DNS check results.

GET /api/v1/domains/{id}

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "verified": true,
    "usageType": "sends-and-receives",
    "testEmailLocalPart": "admin",
    "lastCheckedAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "checks": {
      "mx": { /* MX check results */ },
      "spf": { /* SPF check results */ },
      "dkim": [ /* DKIM check results */ ],
      "dmarc": { /* DMARC check results */ },
      "mtaSts": { /* MTA-STS check results */ },
      "tlsRpt": { /* TLS-RPT check results */ },
      "bimi": { /* BIMI check results */ },
      "dnssec": { /* DNSSEC check results */ }
    }
  }
}

Example

curl -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000

---

Update Domain

Update domain settings.

PATCH /api/v1/domains/{id}

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID

Request Body

Field	Type	Description
usageType	string	How the domain is used
testEmailLocalPart	string	Local part for test email

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "verified": true,
    "usageType": "sends-only",
    "testEmailLocalPart": null,
    "lastCheckedAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}

Example

curl -X PATCH \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"usageType": "sends-only"}' \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000

---

Delete Domain

Remove a domain and all associated data.

DELETE /api/v1/domains/{id}

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID

Response

{
  "data": {
    "deleted": true
  }
}

Example

curl -X DELETE \
  -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000

WARNING

This action cannot be undone. All DNS checks, reports, and alerts for this domain will be permanently deleted.

---

Verify Domain

Check or perform domain ownership verification.

Get Verification Status

GET /api/v1/domains/{id}/verify

Returns the verification status and the required DNS record.

{
  "data": {
    "verified": false,
    "verificationRecord": {
      "hostname": "_mailshield.example.com",
      "type": "TXT",
      "value": "mailshield-verify=abc123xyz"
    }
  }
}

Verify Domain

POST /api/v1/domains/{id}/verify

Attempts to verify the domain by checking for the DNS TXT record.

{
  "data": {
    "verified": true,
    "message": "Domain verified successfully"
  }
}

If verification fails:

{
  "data": {
    "verified": false,
    "message": "Verification record not found",
    "expected": {
      "hostname": "_mailshield.example.com",
      "type": "TXT",
      "value": "mailshield-verify=abc123xyz"
    }
  }
}