Valimail Reporting API Documentation : Valimail Support

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 and the current version is 0.0.1.

Base URL

The base URL for the API is https://api.valimail.com.

Authentication

/auth

This 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 (https://support.valimail.com/support/tickets/new)

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
      }