Skip to main content
All CollectionsValimail SuiteAPI
Valimail Reporting API Documentation
Valimail Reporting API Documentation
Updated over a week ago

Welcome to the Valimail Reporting API documentation. This API provides a way for customers to retrieve reports on senders and unidentified emails. The API is based on the OpenAPI 3.0.0 standard.

Base URL

The URL for the reporting API is https://api.valimail.com/docs/reports.html

Authentication

The URL for the authentication endpoint is https://api.valimail.com/docs/all.html

The /auth endpoint is responsible for generating session tokens once the client-id and app-id have been validated.

If you don’t know your client-id or app-id, please log a ticket and we will be happy to assist you.

Request:

  • POST

  • Content-Type: application/json

Request Body:

{
"client-id": "YOUR_CLIENT_ID",
"app-id": "YOUR_APP_ID"
}

Response:

  • 201 Created: Returns a token and an expiration date in JSON format if the client_id and app_id are validated.

  • 401 Unauthorized: When the authorization token is missing or invalid.

  • 404 Not Found: When the requested resource is not found.

  • 422 Unprocessable Entity: When the request parameters are invalid.

  • 500 Internal Server Error: When there is an error with the server.

Response Body:

{
"token": "YOUR_TOKEN",
"expires_at": "2023-05-10T08:00:00Z"
}

Usage:

Once you have obtained your token, you'll need to add it as an Authorization header in any subsequent requests, using the format of

{
"Authorization": "Bearer YOUR_TOKEN"
}

Endpoints

The API has the following endpoints:

/accounts/{slug}/reports/senders

This endpoint returns a report on senders for a specific account.

Request Parameters:

  • slug: (required) The account slug for which the report is requested.

  • domains: (optional) An array of domains to filter the report on.

  • start-date: (required) The start date for the report in ISO 8601 format.

  • end-date: (required) The end date for the report in ISO 8601 format.

  • reverse: (optional) A boolean value to reverse the order of the report.

  • sort-key: (optional) A string value to sort the report on.

  • page: (optional) An integer value for pagination purposes.

  • per-page: (optional) An integer value to specify the number of results per page.

  • help: (optional) A boolean value to display help information.

Response:

  • 200 OK: Returns the senders report in JSON format.

Senders Report Schema:

  • service-name: A string value representing the name of the service.

  • service-status: A string value representing the status of the service.

  • passing-percentage: A number value representing the percentage of passing messages.

  • total-messages-count: An integer value representing the total number of messages.

  • dmarc-passing-count: An integer value representing the number of DMARC passing messages.

  • dmarc-failing-count: An integer value representing the number of DMARC failing messages.

  • allowed-through-no-enforcement-count: An integer value representing the number of messages allowed through with no enforcement.

  • allowed-through-with-enforcement-count: An integer value representing the number of messages allowed through with enforcement.

  • aligned-spf-count: An integer value representing the number of messages with aligned SPF.

  • failing-spf-count: An integer value representing the number of messages failing SPF.

  • unaligned-spf-count: An integer value representing the number of messages with unaligned SPF.

  • dmarc-overridden-count: An integer value representing the number of messages with DMARC overridden.

  • quarantined-count: An integer value representing the number of quarantined messages.

  • rejected-count: An integer value representing the number of rejected messages.

Error Responses:

  • 400 Bad Request: When a required parameter is missing or invalid.

  • 404 Not Found: When the requested resource is not found.

  • 500 Internal Server Error: When there is an error with the server.

Example Request:

GET https://api.valimail.com/accounts/my-account/reports/senders?domains=example.com&start-date=2023-05-01T00:00:00.0Z&end-date=22023-05-04T00:00:00.0Z&sort-key=service-name&page=1&per-page=20

Example Response:

  {
    "service-name": "example_esp",
    "service-status": "pass",
    "passing-percentage": 99.9,
    "total-messages-count": 1000,
    "dmarc-passing-count": 900,
    "dmarc-failing-count": 100,
    "allowed-through-no-enforcement-count": 100,
    "allowed-through-with-enforcement-count": 100,
    "aligned-spf-count": 950,
    "failing-spf-count": 50,
    "unaligned-spf-count": 0,
    "dmarc-overridden-count": 0,
    "quarantined-count": 0,
    "rejected-count": 0
    }
    

/accounts/{slug}/reports/unidentified

This endpoint returns a report on unidentified emails for a specific account.

Request Parameters:

  • slug: (required) The account slug for which the report is requested.

  • domains: (optional) An array of domains to filter the report on.

  • start-date: (required) The start date for the report in ISO 8601 format.

  • end-date: (required) The end date for the report in ISO 8601 format.

  • reverse: (optional) A boolean value to reverse the order of the report.

  • sort-key: (optional) A string value to sort the report on.

  • page: (optional) An integer value for pagination purposes.

  • per-page: (optional) An integer value to specify the number of results per page.

  • help: (optional) A boolean value to display help information.

Response:

  • 200 OK: Returns the unidentified report in JSON format.

Unidentified Report Schema:

  • ptr-name: A string value representing the PTR name.

  • source-ip: A string value representing the source IP address.

  • geo-country-code: A string value representing the country code for the location.

  • spf-domain: A string value representing the SPF domain.

  • dmarc-policy-org-domain: A string value representing the DMARC policy organization domain.

  • passing-percentage: A number value representing the percentage of passing messages.

  • total-messages-count: An integer value representing the total number of messages.

  • dmarc-passing-count: An integer value representing the number of DMARC passing messages.

  • dmarc-failing-count: An integer value representing the number of DMARC failing messages.

  • allowed-through-no-enforcement-count: An integer value representing the number of messages allowed through with no enforcement.

  • allowed-through-with-enforcement-count: An integer value representing the number of messages allowed through with enforcement.

  • aligned-spf-count: An integer value representing the number of messages with aligned SPF.

  • failing-spf-count: An integer value representing the number of messages failing SPF.

  • unaligned-spf-count: An integer value representing the number of messages with unaligned SPF.

  • dmarc-overridden-count: An integer value representing the number of messages with DMARC overridden.

  • quarantined-count: An integer value representing the number of quarantined messages.

  • rejected-count: An integer value representing the number of rejected messages.

Error Responses:

  • 400 Bad Request: When a required parameter is missing or invalid.

  • 404 Not Found: When the requested resource is not found.

  • 500 Internal Server Error: When there is an error with the server.

Example Request:

GET https://api.valimail.com/accounts/my-account/reports/unidentified?domains=example.com&2023-05-01T00:00:00.0Z&end-date=22023-05-04T00:00:00.0Z&sort-key=ptr-name&page=1&per-page=20

Example Response:

    {
      "ptr-name": "mail.example.com",
      "source-ip": "192.0.2.1",
      "geo-country-code": "US",
      "spf-domain": "example.com",
      "dmarc-policy-org-domain": "yourdomain.com",
      "passing-percentage": 99.9,
      "total-messages-count": 1000,
      "dmarc-passing-count": 900,
      "dmarc-failing-count": 100,
      "allowed-through-no-enforcement-count": 100,
      "allowed-through-with-enforcement-count": 100,
      "aligned-spf-count": 950,
      "failing-spf-count": 50,
      "unaligned-spf-count": 0,
      "dmarc-overridden-count": 0,
      "quarantined-count": 0,
      "rejected-count": 0
      }
      
Did this answer your question?