API Reference

GET /api/v1/org

get
Description
Get organization for bearer API key
Required Role
read
Example Request Body
No request body.
Query Parameters
No query parameters.
Example Response
Type: OrganizationResponse
{
  "data": {
    "id": "67dcf43bfd4f88e25d9d569b",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "createdAt": "2026-03-31T12:00:00.000Z",
    "logo": null,
    "metadata": {}
  }
}

GET /api/v1/org/{orgId}/domains

get
Description
List domains for an organization
Required Role
read
Example Request Body
No request body.
Query Parameters
name
string optional
Optional exact domain name filter.
Example: example.com
Example Response
Type: DomainCollectionResponse
{
  "data": [
    {
      "id": "67dcf5f5fd4f88e25d9d56a1",
      "ts": 1711886400000,
      "organizationId": "67dcf43bfd4f88e25d9d569b",
      "name": "example.com",
      "isOrganizationalDomain": true,
      "isHidden": false
    }
  ],
  "meta": {
    "total": 1
  }
}

POST /api/v1/org/{orgId}/domains

post
Description
Create a domain for an organization
Required Role
write
Example Request Body
{
  "domain": "example.com"
}
Query Parameters
No query parameters.
Example Response
Type: DomainResponse
{
  "data": {
    "id": "67dcf5f5fd4f88e25d9d56a1",
    "ts": 1711886400000,
    "organizationId": "67dcf43bfd4f88e25d9d569b",
    "name": "example.com",
    "isOrganizationalDomain": true,
    "isHidden": false
  }
}

POST /api/v1/org/{orgId}/domains/bulk

post
Description
Create multiple domains for an organization
Required Role
write
Example Request Body
{
  "domains": [
    "example.com",
    "mail.example.com"
  ]
}
Query Parameters
No query parameters.
Example Response
Type: DomainCollectionResponse
{
  "data": [
    {
      "id": "67dcf5f5fd4f88e25d9d56a1",
      "ts": 1711886400000,
      "organizationId": "67dcf43bfd4f88e25d9d569b",
      "name": "example.com",
      "isOrganizationalDomain": true,
      "isHidden": false
    }
  ],
  "meta": {
    "total": 1
  }
}

GET /api/v1/org/{orgId}/domains/{domainId}/setup

get
Description
Get DMARC setup guidance for a domain
Required Role
read
Example Request Body
No request body.
Query Parameters
No query parameters.
Example Response
Type: DomainSetupResponse
{
  "data": {
    "domainId": "67dcf5f5fd4f88e25d9d56a1",
    "domain": "example.com",
    "receiverAddress": "67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io",
    "dnsProvider": {
      "nameservers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "provider": "Cloudflare"
    },
    "current": {
      "lookup": {
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false,
        "raw": "v=DMARC1; p=none"
      },
      "record": {
        "ts": 1711886400000,
        "raw": "v=DMARC1; p=none",
        "version": "DMARC1",
        "policy": "none",
        "unknownTags": {},
        "tags": [
          "v=DMARC1",
          "p=none"
        ],
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false
      }
    },
    "recommended": {
      "action": "update",
      "hostname": "_dmarc.example.com",
      "recordType": "TXT",
      "ttlSeconds": 3600,
      "value": "v=DMARC1; p=none; rua=mailto:67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io",
      "lookup": {
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false,
        "raw": "v=DMARC1; p=none; rua=mailto:67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io"
      },
      "record": {
        "ts": 1711886400000,
        "raw": "v=DMARC1; p=none; rua=mailto:67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io",
        "version": "DMARC1",
        "policy": "none",
        "aggregateReportUris": [
          {
            "raw": "mailto:67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io",
            "scheme": "mailto",
            "address": "67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io",
            "params": {}
          }
        ],
        "unknownTags": {},
        "tags": [
          "v=DMARC1",
          "p=none",
          "rua=mailto:67dcf5f5fd4f88e25d9d56a1@in.dmarcdefender.io"
        ],
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false
      }
    }
  }
}

GET /api/v1/org/{orgId}/domains/{domainId}/health

get
Description
Get recommendations, grade, and DNS health details for a domain
Required Role
read
Example Request Body
No request body.
Query Parameters
No query parameters.
Example Response
Type: DomainHealthResponse
{
  "data": {
    "domainId": "67dcf5f5fd4f88e25d9d56a1",
    "domain": "example.com",
    "timestamp": "2026-03-31T12:00:00.000Z",
    "grade": "B",
    "score": {
      "score": 82,
      "grade": "B"
    },
    "recommendations": [
      {
        "title": "No aggregate report URI configured",
        "category": "dmarc",
        "severity": "warning",
        "description": "No aggregate report URI (rua) is configured.",
        "remediation": "Add a rua destination to your DMARC record.",
        "docs": [
          {
            "title": "DMARC Explained",
            "url": "https://dmarcdefender.io/docs/dmarc-explained"
          }
        ]
      }
    ],
    "dmarc": {
      "lookup": {
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false,
        "raw": "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
      },
      "record": {
        "ts": 1711886400000,
        "raw": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
        "version": "DMARC1",
        "policy": "none",
        "unknownTags": {},
        "tags": [
          "v=DMARC1",
          "p=none",
          "rua=mailto:dmarc@example.com"
        ],
        "domain": "example.com",
        "organizationalDomain": "example.com",
        "isUsingParentRecord": false
      }
    },
    "spf": {
      "lookup": {
        "domain": "example.com",
        "raw": "v=spf1 include:_spf.google.com ~all"
      },
      "record": {},
      "tree": {}
    },
    "dkim": {
      "selectors": [
        "google"
      ],
      "records": []
    },
    "bimi": {
      "lookup": {
        "domain": "example.com",
        "selector": "default",
        "raw": ""
      },
      "record": null
    },
    "tlsRpt": {
      "lookup": {
        "domain": "example.com",
        "raw": "v=TLSRPTv1; rua=mailto:tlsrpt@example.com"
      },
      "record": {}
    },
    "mtaSts": {
      "lookup": {
        "domain": "example.com",
        "raw": "version: STSv1",
        "policy": "mode: testing"
      },
      "record": {}
    },
    "mxRecords": [
      {
        "exchange": "aspmx.l.google.com",
        "priority": 1
      }
    ],
    "dnsProvider": {
      "nameservers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "provider": "Cloudflare"
    }
  }
}

GET /api/v1/org/{orgId}/domains/{domainId}/volume

get
Description
Get DMARC email volume totals for a domain
Required Role
read
Example Request Body
No request body.
Query Parameters
days
number optional
Lookback window in days. Defaults to 30.
Example: 30
Example Response
Type: DomainVolumeResponse
{
  "data": {
    "totalEmails": 1932,
    "dmarcPasses": 1825,
    "dmarcQuarantines": 33,
    "dmarcRejects": 41,
    "dmarcOverrides": 14,
    "days": 30
  }
}

DELETE /api/v1/org/{orgId}/domains/{domainId}

delete
Description
Delete a domain from an organization
Required Role
write
Example Request Body
No request body.
Query Parameters
No query parameters.
Example Response
Type: DomainResponse
{
  "data": {
    "id": "67dcf5f5fd4f88e25d9d56a1",
    "ts": 1711886400000,
    "organizationId": "67dcf43bfd4f88e25d9d569b",
    "name": "example.com",
    "isOrganizationalDomain": true,
    "isHidden": false
  }
}

GET /api/v1/org/{orgId}/audit-logs

get
Description
List audit logs for an organization
Required Role
read
Example Request Body
No request body.
Query Parameters
page
number optional
1-based page number for the audit log result set.
Example: 1
Example Response
Type: AuditLogCollectionResponse
{
  "data": [
    {
      "id": "67dd0000fd4f88e25d9d57aa",
      "ts": 1711886400000,
      "organizationId": "67dcf43bfd4f88e25d9d569b",
      "organizationName": "Acme Corp",
      "apiKeyId": "67dd1111fd4f88e25d9d57ab",
      "action": "domain_added",
      "message": "Domain example.com added",
      "data": {
        "domain": "example.com"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 1000,
    "total": 42
  }
}

GET /api/v1/org/{orgId}/ingestion-events

get
Description
List ingestion events for an organization
Required Role
read
Example Request Body
No request body.
Query Parameters
page
number optional
1-based page number for the ingestion result set.
Example: 1
limit
number optional
Page size for the ingestion result set. Max 200.
Example: 50
domainId
undefined optional
Optional domain id filter.
Example:
Example Response
Type: IngestionEventCollectionResponse
{
  "data": [
    {
      "id": "67dcfb46fd4f88e25d9d5703",
      "ts": 1711906200000,
      "organizationId": "67dcf43bfd4f88e25d9d569b",
      "domainId": "67dcf5f5fd4f88e25d9d56a1",
      "aggregateReportIds": [
        "67dcfb46fd4f88e25d9d5704"
      ],
      "fileNames": [
        "report.xml.gz"
      ],
      "storageURLs": [
        "https://blob.example/report.xml.gz"
      ],
      "source": "postmark",
      "status": "completed",
      "totalEmails": 1932,
      "domains": [
        "example.com"
      ]
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 1
  }
}