Reports

Access DMARC aggregate reports and TLS-RPT reports for your domains.

DMARC Reports

List DMARC Reports

GET /api/v1/domains/{id}/reports/dmarc

Returns DMARC aggregate reports for a domain.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
startDate	datetime	-	Filter by start date (ISO 8601)
endDate	datetime	-	Filter by end date (ISO 8601)
includeRecords	boolean	false	Include individual report records

Response

{
  "data": {
    "reports": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reportId": "12345678901234567890",
        "orgName": "google.com",
        "email": "noreply-dmarc-support@google.com",
        "dateRangeBegin": "2024-01-14T00:00:00Z",
        "dateRangeEnd": "2024-01-15T00:00:00Z",
        "policyDomain": "example.com",
        "policyP": "reject",
        "policySp": null,
        "policyAdkim": "r",
        "policyAspf": "r",
        "policyPct": 100,
        "totalCount": 1250,
        "passCount": 1240,
        "failCount": 10,
        "receivedAt": "2024-01-15T06:30:00Z"
      }
    ],
    "summary": {
      "totalReports": 15,
      "totalMessages": 25000,
      "passedMessages": 24850,
      "failedMessages": 150,
      "passRate": 99
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Example

# Get last 7 days of DMARC reports
curl -H "Authorization: Bearer ms_your_token" \
  "https://app.mailshield.app/api/v1/domains/550e8400.../reports/dmarc?startDate=2024-01-08T00:00:00Z"

With Individual Records

When includeRecords=true, each report includes detailed records:

{
  "reports": [
    {
      "id": "...",
      "orgName": "google.com",
      "totalCount": 1250,
      "records": [
        {
          "id": "...",
          "sourceIp": "203.0.113.1",
          "count": 500,
          "disposition": "none",
          "dkim": "pass",
          "spf": "pass",
          "headerFrom": "example.com",
          "dkimResults": [
            {"domain": "example.com", "result": "pass", "selector": "google"}
          ],
          "spfResults": [
            {"domain": "example.com", "result": "pass"}
          ]
        }
      ]
    }
  ]
}

---

TLS Reports

List TLS-RPT Reports

GET /api/v1/domains/{id}/reports/tls

Returns TLS-RPT reports for a domain.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
startDate	datetime	-	Filter by start date (ISO 8601)
endDate	datetime	-	Filter by end date (ISO 8601)
includePolicies	boolean	false	Include policy details

Response

{
  "data": {
    "reports": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reportId": "smtp-tls-report-12345",
        "organizationName": "Google Inc.",
        "contactInfo": "smtp-tls-reporting@google.com",
        "dateRangeBegin": "2024-01-14T00:00:00Z",
        "dateRangeEnd": "2024-01-15T00:00:00Z",
        "totalSuccessCount": 5000,
        "totalFailureCount": 5,
        "receivedAt": "2024-01-15T08:00:00Z"
      }
    ],
    "summary": {
      "totalReports": 10,
      "totalConnections": 50050,
      "successfulConnections": 50000,
      "failedConnections": 50,
      "successRate": 99
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Example

curl -H "Authorization: Bearer ms_your_token" \
  "https://app.mailshield.app/api/v1/domains/550e8400.../reports/tls?includePolicies=true"

With Policy Details

When includePolicies=true, each report includes policy information:

{
  "reports": [
    {
      "id": "...",
      "organizationName": "Google Inc.",
      "totalSuccessCount": 5000,
      "totalFailureCount": 5,
      "policies": [
        {
          "id": "...",
          "policyType": "sts",
          "policyDomain": "example.com",
          "policyString": ["version: STSv1", "mode: enforce"],
          "mxHost": "mail.example.com",
          "successCount": 4995,
          "failureCount": 5,
          "failureDetails": [
            {
              "resultType": "certificate-expired",
              "sendingMtaIp": "172.217.0.1",
              "receivingMxHostname": "mail.example.com",
              "failedSessionCount": 5
            }
          ]
        }
      ]
    }
  ]
}

---

Report Summary Statistics

Both report types include summary statistics in the response:

DMARC Summary

Field	Description
totalReports	Number of reports in response
totalMessages	Total messages across all reports
passedMessages	Messages that passed DMARC
failedMessages	Messages that failed DMARC
passRate	Percentage of passed messages

TLS Summary

Field	Description
totalReports	Number of reports in response
totalConnections	Total connection attempts
successfulConnections	Successful TLS connections
failedConnections	Failed TLS connections
successRate	Percentage of successful connections