Rate a Email API Documentation
Access email reputation data programmatically. Use our simple REST API to retrieve reviews and profile summaries for specific email addresses.
Get Reviews & Profile by Email
Fetch a list of reviews and aggregate profile data for a specific email address.

Endpoint

GET /api/reviews

Query Parameters

  • email (string, required): The email address you want to retrieve data for.
  • limit (number, optional): The maximum number of individual reviews to return (default: 20, max: 100). This limit applies *after* anonymous reviews are filtered, if applicable based on the email's settings.

Example Request (cURL)

curl "/api/reviews?email=test%40example.com&limit=5"

Example Request (JavaScript Fetch)

fetch("/api/reviews?email=test%40example.com&limit=5")
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Email Profile:', data.emailProfile);
    console.log('Reviews:', data.reviews);
  })
  .catch(error => {
    console.error("Fetch error:", error);
  });

Response Structure

The API returns a JSON object containing an emailProfile object and an array of reviews.

Email Profile Object (emailProfile)

Contains aggregate data and settings for the queried email. Will be null if the email profile does not exist.

  • email: The queried email address.
  • averageRating: The average star rating (1-5), or null if no ratings.
  • ratingCount: Total number of ratings.
  • ratingBreakdown: An object showing counts for each star rating (e.g., {"5": 10, "4": 5, ...}).
  • isPublicViewRestricted: Boolean indicating if the email owner has restricted public view of review details.
  • areAnonymousReviewsHidden: Boolean indicating if the email owner has chosen to hide anonymous reviews from public display.
  • lastReviewedAt: ISO 8601 timestamp of the most recent review, or null.

Review Object (within reviews array)

Represents an individual review. Fields may be limited based on email owner's settings.

  • id: Unique ID of the review. (Always present)
  • rating: The star rating (1-5). (Always present)
  • email: The email address that was reviewed. (Always present)
  • text: Optional review text.
    Omitted if public view restricted
  • createdAt: ISO 8601 timestamp.
    Omitted if public view restricted
  • isAnonymous: Boolean.
    Omitted if public view restricted
  • replyText: Owner's reply text, if any.
    Omitted if public view restricted
  • replyCreatedAt: ISO 8601 timestamp of owner's reply.
    Omitted if public view restricted

If emailProfile.isPublicViewRestricted is true, review objects will only contain id, rating, and email.

If emailProfile.areAnonymousReviewsHidden is true, reviews where isAnonymous would be true are excluded from the reviews array.

Example Success Response (200 OK)

Full Details:

{
  "emailProfile": {
    "email": "test@example.com",
    "averageRating": 4.2,
    "ratingCount": 25,
    "ratingBreakdown": { "1": 1, "2": 2, "3": 5, "4": 8, "5": 9 },
    "isPublicViewRestricted": false,
    "areAnonymousReviewsHidden": false,
    "lastReviewedAt": "2024-03-10T12:00:00.000Z"
  },
  "reviews": [
    {
      "id": "reviewDocId1",
      "rating": 5,
      "text": "Excellent experience!",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "email": "test@example.com",
      "isAnonymous": false,
      "replyText": "Thank you for your kind words!",
      "replyCreatedAt": "2024-01-16T09:00:00.000Z"
    },
    {
      "id": "reviewDocId2",
      "rating": 1,
      "createdAt": "2024-01-14T15:00:00.000Z",
      "email": "test@example.com",
      "isAnonymous": true
    },
    // ... more reviews up to the limit
  ]
}

With Public View Restricted:

{
  "emailProfile": {
    "email": "restricted@example.com",
    "averageRating": 3.5,
    "ratingCount": 10,
    "ratingBreakdown": { "1": 0, "2": 1, "3": 6, "4": 2, "5": 1 },
    "isPublicViewRestricted": true,
    "areAnonymousReviewsHidden": false,
    "lastReviewedAt": "2024-03-01T18:00:00.000Z"
  },
  "reviews": [ // Note: Review details are limited
    {
      "id": "reviewDocIdRestricted1",
      "rating": 4,
      "email": "restricted@example.com"
    },
    {
      "id": "reviewDocIdRestricted2",
      "rating": 3,
      "email": "restricted@example.com"
    }
    // ... more review stubs up to the limit
  ]
}

Error Responses

  • 400 Bad Request: Returned if the email parameter is missing, invalid, or the limit is invalid.
    {
  "error": "Valid email query parameter is required."
}
  • 500 Internal Server Error: Returned if there was an unexpected error on the server.
    {
  "error": "Internal Server Error"
}
Explore more on the site: Search Emails