MailShield Docs

Appearance

Domains ​

Manage domains in your organization.

Report ingest addresses ​

Every domain has its own report mailbox. Publish it in your DMARC rua/ruf tags and your TLS-RPT rua tag so reports reach MailShield.

The address is returned as a reporting object on every domain response — create, list, get and update — so a scripted onboarding can publish DNS in the same pass that creates the domain:

json
"reporting": {
  "ruaAddress": "mailto:942d71ef@reports.mailshield.app",
  "rufAddress": "mailto:942d71ef@reports.mailshield.app",
  "tlsRptAddress": "mailto:942d71ef@reports.mailshield.app"
}

All three currently resolve to the same mailbox. They are named separately so your integration binds to a per-report-type contract rather than to that fact.

WARNING

Use the address exactly as returned. A rua pointing at the wrong mailbox fails silently — reports are simply never delivered, with no error anywhere.

List Domains ​

Returns a paginated list of all domains.

GET /api/v1/domains

Query Parameters ​

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger20Items per page (max 100)

Response ​

json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "example.com",
      "verified": true,
      "usageType": "sends-and-receives",
      "testEmailLocalPart": "admin",
      "reporting": {
        "ruaAddress": "mailto:942d71ef@reports.mailshield.app",
        "rufAddress": "mailto:942d71ef@reports.mailshield.app",
        "tlsRptAddress": "mailto:942d71ef@reports.mailshield.app"
      },
      "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 ​

bash
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 ​

FieldTypeRequiredDescription
domainstringYesDomain name (e.g., "example.com")
usageTypestringNoHow the domain is used (default: "sends-and-receives")
testEmailLocalPartstringConditionalRequired 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) ​

json
{
  "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",
    "reporting": {
      "ruaAddress": "mailto:942d71ef@reports.mailshield.app",
      "rufAddress": "mailto:942d71ef@reports.mailshield.app",
      "tlsRptAddress": "mailto:942d71ef@reports.mailshield.app"
    }
  }
}

Example ​

bash
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 ​

ParameterTypeDescription
iduuidDomain ID

Response ​

json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "verified": true,
    "usageType": "sends-and-receives",
    "testEmailLocalPart": "admin",
    "reporting": {
      "ruaAddress": "mailto:942d71ef@reports.mailshield.app",
      "rufAddress": "mailto:942d71ef@reports.mailshield.app",
      "tlsRptAddress": "mailto:942d71ef@reports.mailshield.app"
    },
    "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 ​

bash
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 ​

ParameterTypeDescription
iduuidDomain ID

Request Body ​

FieldTypeDescription
usageTypestringHow the domain is used
testEmailLocalPartstringLocal part for test email

Response ​

json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "verified": true,
    "usageType": "sends-only",
    "testEmailLocalPart": null,
    "reporting": {
      "ruaAddress": "mailto:942d71ef@reports.mailshield.app",
      "rufAddress": "mailto:942d71ef@reports.mailshield.app",
      "tlsRptAddress": "mailto:942d71ef@reports.mailshield.app"
    },
    "lastCheckedAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}

Example ​

bash
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 ​

ParameterTypeDescription
iduuidDomain ID

Response ​

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

Example ​

bash
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.

json
{
  "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.

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

If verification fails:

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

Monitor and secure your email domains.

Copyright © 2026 MailShield