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, newest first.

Mail forwarded from mailbox providers such as Gmail or Outlook counts as neither passed nor failed: passCount + failCount + forwardedCount = totalCount, and pass rates are over passed plus failed. See Forwarded mail below.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page, 1 to 100. Larger values return 100
startDate	date or datetime	none	Only reports whose range begins at or after this time
endDate	date or datetime	none	Only reports whose range ends at or before this time
includeRecords	boolean	false	Include individual report records

Dates are ISO 8601: a date such as 2024-01-08 (midnight UTC) or a date-time such as 2024-01-08T00:00:00Z. A date-time without an offset is read as UTC. An invalid date, a startDate after endDate, or a page or limit that isn't a whole number returns 400.

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": 1232,
        "failCount": 10,
        "forwardedCount": 8,
        "receivedAt": "2024-01-15T06:30:00Z"
      }
    ],
    "summary": {
      "totalReports": 15,
      "totalMessages": 25000,
      "passedMessages": 24700,
      "failedMessages": 150,
      "forwardedMessages": 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"}
          ],
          "forwarded": false
        }
      ]
    }
  ]
}

Each record's forwarded says whether it's counted in the report's forwardedCount instead of its passCount or failCount.

Forwarded mail

When someone forwards your mail from their Gmail, Outlook or other mailbox, SPF fails at the forwarding server by design. MailShield flags a record as forwarded when:

1. The sending server's reverse DNS hostname belongs to a mailbox provider (Google, Microsoft, Yahoo and AOL, iCloud, Proton, Fastmail, Zoho, GMX and Web.de, Yandex or Mail.ru), and
2. SPF didn't pass aligned, and
3. the domain's SPF record doesn't include that provider's SPF include (directly or nested), or DKIM passed aligned.

Forwarded records count toward totalCount and totalMessages, like every message, but not toward passCount, failCount or the pass rate. The flag is set when a report arrives. See Forwarded Mail.

---

TLS Reports

List TLS-RPT Reports

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

Returns TLS-RPT reports for a domain, newest first.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page, 1 to 100. Larger values return 100
startDate	date or datetime	none	Only reports whose range begins at or after this time
endDate	date or datetime	none	Only reports whose range ends at or before this time
includePolicies	boolean	false	Include policy details

Dates and paging work the same way as for DMARC reports.

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. The summary covers every report that matches startDate and endDate, across all pages, so it's the same on every page.

DMARC Summary

Field	Description
totalReports	Number of reports in the date range
totalMessages	Total messages across those reports, forwarded ones included
passedMessages	Messages that passed DMARC
failedMessages	Messages that failed DMARC
forwardedMessages	Messages forwarded from mailbox providers, counted as neither passed nor failed
passRate	passedMessages as a percentage of passedMessages + failedMessages, rounded, or null when both are 0

passedMessages + failedMessages + forwardedMessages = totalMessages.

TLS Summary

Field	Description
totalReports	Number of reports in the date range
totalConnections	Total connection attempts
successfulConnections	Successful TLS connections
failedConnections	Failed TLS connections
successRate	Percentage of successful connections, rounded, or null without connections