This is a guide on how to run basic requests for the Valimail Reporting API in Postman. API credentials will be required in order to utilize the reporting API.



Authentication

  • Send a POST to the auth endpoint using the Authentication request. The app-id and client-id should not need to be changed unless the credentials have been updated. 

  • Use the token value for subsequent requests


Senders Report

  • In the GET URL field, update SLUG-HERE to the account slug you wish to retrieve data for
  • On the Headers tab, edit the Authorization header and replace SESSION_TOKEN_HERE with the token value from the Authentication request
  • In the Params tab, add two keys for the start-date and end-date, make sure to enter the value of the dates using ISO 8601 format
  • In the Body tab, edit the parameters to suit the needs of your request
  • Click Send when ready. If your request was successful, you’ll receive a response in the response window with the requested data


Unidentified Report

  • In the GET URL field, update SLUG-HERE to the account slug you wish to retrieve data for
  • On the Headers tab, edit the Authorization header and replace SESSION_TOKEN_HERE with the token value from the Authentication request
  • In the Params tab, add two keys for the start-date and end-date, make sure to enter the value of the dates using ISO 8601 format
  • In the Body tab, edit the parameters to suit the needs of your request
  • Click Send when ready. If your request was successful, you’ll receive a response in the response window with the requested data


Request Parameters 

Required:

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

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

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

Optional:

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

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

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

  • page: An integer value for pagination purposes.

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

  • help: A boolean value to display help information.


Possible Responses

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

  • 201 Created: Returns a token and an expiration date in JSON format if the client-id and app-id are validated.

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

  • 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.



Examples of Postman for Reference: 


In the Body for Authentication, you will be entering the app-id and client-id to receive the token.


In Headers for Senders/Unidentified Reports, you will input the token you have received after the word Bearer. 


In Params for Senders/Unidentified Reports, you will enter the required requests of start-date and end-date in ISO 8601 format. Here, you can also add any optional requests.


In Body for Senders/Unidentified Reports, add any domain names you would like to receive a report for. Also, make sure to add your SLUG in the URL.


Lastly, once these steps are complete you can hit SEND to receive the report.


For more instructions: Valimail Reporting API