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
      }