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
}