Client Domain Email Trends - COMPASS API Documentation

Get incoming email trends for top client domains

curl --request GET \
  --url http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate} \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "",
  "data": {
    "labels": [
      "example.com",
      "client.org",
      "partner.net"
    ],
    "series": [
      {
        "name": "example.com",
        "data": [
          3,
          6,
          4,
          2,
          7,
          5,
          8
        ]
      },
      {
        "name": "client.org",
        "data": [
          1,
          4,
          3,
          5,
          2,
          1,
          0
        ]
      }
    ]
  }
}

GET

email-meter

stats

clients

incoming-emails-trend

{startDate}

{endDate}

Get incoming email trends for top client domains

curl --request GET \
  --url http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate} \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/{startDate}/{endDate}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "",
  "data": {
    "labels": [
      "example.com",
      "client.org",
      "partner.net"
    ],
    "series": [
      {
        "name": "example.com",
        "data": [
          3,
          6,
          4,
          2,
          7,
          5,
          8
        ]
      },
      {
        "name": "client.org",
        "data": [
          1,
          4,
          3,
          5,
          2,
          1,
          0
        ]
      }
    ]
  }
}

Returns the daily incoming email trends for the top 5 client domains within the specified date range. Only incoming emails are counted. The response provides a series array suitable for time-series visualization.

Request

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token

Path Parameters

Parameter	Type	Required	Description
startDate	string	Yes	Start date for the trend range (YYYY-MM-DD)
endDate	string	Yes	End date for the trend range (YYYY-MM-DD)

Parameter Format

Format: YYYY-MM-DD (ISO 8601 date)
Timezone: UTC
Default: Last 7 days if not provided

Response

200 OK - Successfully retrieved incoming email trends for top client domains

{
  "message": "",
  "data": {
    "labels": [
      "2025-10-01",
      "2025-10-02",
      "2025-10-03",
      "2025-10-04",
      "2025-10-05",
      "2025-10-06",
      "2025-10-07"
    ],
    "series": [
      {
        "name": "gmail.com",
        "data": [12, 15, 8, 22, 18, 25, 20]
      },
      {
        "name": "yahoo.com",
        "data": [8, 10, 6, 15, 12, 18, 14]
      },
      {
        "name": "company.com",
        "data": [5, 7, 4, 10, 8, 12, 9]
      },
      {
        "name": "outlook.com",
        "data": [6, 8, 5, 12, 10, 14, 11]
      },
      {
        "name": "hotmail.com",
        "data": [4, 6, 3, 8, 7, 10, 8]
      }
    ]
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}

Example

curl -X GET 'http://localhost:2000/email-meter/stats/clients/incoming-emails-trend/2025-10-01/2025-10-20' \
  -H 'Authorization: Bearer your-jwt-token'

Data Structure

Labels Array

Field	Type	Description
labels	array	List of dates in YYYY-MM-DD format

Series Array

Each object represents a domain’s daily email counts:

Field	Type	Description
name	string	Domain name
data	array	Daily incoming email counts

Data Alignment

series[i].data[j] corresponds to labels[j] for the domain series[i].name
All data arrays have the same length as labels
Only incoming emails are counted (outgoing emails excluded)

Use Cases

Client Behavior Analysis: Track email patterns by domain
Capacity Planning: Predict volume from top domains
Service Level Management: Monitor domain-specific service levels
Trend Identification: Spot increasing/decreasing domain activity
Visualization: Create multi-line charts for domain trends

Analysis Examples

Domain Growth Analysis

const analyzeGrowth = (data) => {
  return data.series.map(domain => {
    const firstDay = domain.data[0];
    const lastDay = domain.data[domain.data.length - 1];
    const growth = ((lastDay - firstDay) / firstDay) * 100;
    const average = domain.data.reduce((a, b) => a + b, 0) / domain.data.length;
    
    return {
      domain: domain.name,
      firstDay,
      lastDay,
      growth: growth.toFixed(2),
      average: average.toFixed(2),
      trend: growth > 0 ? 'growing' : growth < 0 ? 'declining' : 'stable'
    };
  });
};

Peak Day Identification

const findPeakDays = (data) => {
  return data.series.map(domain => {
    const maxVolume = Math.max(...domain.data);
    const peakDayIndex = domain.data.indexOf(maxVolume);
    const peakDay = data.labels[peakDayIndex];
    
    return {
      domain: domain.name,
      peakDay,
      peakVolume: maxVolume,
      peakDayIndex
    };
  });
};

Correlation Analysis

const calculateCorrelation = (domain1, domain2) => {
  const n = Math.min(domain1.data.length, domain2.data.length);
  const sum1 = domain1.data.slice(0, n).reduce((a, b) => a + b, 0);
  const sum2 = domain2.data.slice(0, n).reduce((a, b) => a + b, 0);
  
  // Simple correlation calculation
  const correlation = n > 1 ? 
    (n * sum1 * sum2 - sum1 * sum2) / 
    Math.sqrt((n * sum1 * sum1 - sum1 * sum1) * (n * sum2 * sum2 - sum2 * sum2)) : 0;
    
  return correlation;
};

Visualization Examples

Multi-Line Chart

const ctx = document.getElementById('domainTrends').getContext('2d');
new Chart(ctx, {
  type: 'line',
  data: {
    labels: response.data.labels,
    datasets: response.data.series.map(domain => ({
      label: domain.name,
      data: domain.data,
      borderColor: `hsl(${Math.random() * 360}, 70%, 50%)`,
      backgroundColor: `hsla(${Math.random() * 360}, 70%, 50%, 0.1)`,
      tension: 0.4
    }))
  },
  options: {
    responsive: true,
    scales: {
      y: {
        beginAtZero: true,
        title: {
          display: true,
          text: 'Incoming Emails'
        }
      }
    },
    plugins: {
      legend: {
        position: 'top'
      }
    }
  }
});

Stacked Area Chart

new Chart(ctx, {
  type: 'line',
  data: {
    labels: response.data.labels,
    datasets: response.data.series.map((domain, index) => ({
      label: domain.name,
      data: domain.data,
      fill: index === 0 ? 'origin' : '-1', // Stacked fill
      backgroundColor: `hsla(${index * 72}, 70%, 50%, 0.6)`,
      borderColor: `hsl(${index * 72}, 70%, 50%)`
    }))
  }
});

Best Practices

Date Range: Use reasonable ranges (recommended: max 90 days)
Focus: Top 5 domains provide focused view without overwhelming data
Comparison: Compare trends across domains for insights
Baseline: Establish baseline patterns for anomaly detection
Regular Updates: Update trends regularly for current insights

Performance Considerations

Data Volume: Multiple series increase data complexity
Caching: Results cached for 15 minutes by default
Processing: Larger date ranges take longer to process
Memory: Consider client-side memory for large datasets

Use /email-meter/stats/clients/top-domains for current top domains
Use /email-meter/stats/emails-trend for overall email trends
Use /email-meter/stats/clients/response-times for domain performance

Notes

Only incoming emails are included in counts
Top 5 domains are based on total volume in the date range
Zero-volume days are included for complete timeline
Data is calculated based on email receipt timestamps
Internal domains may be excluded based on configuration

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

startDate

string<date>

required

Start date for the trend range (YYYY-MM-DD)

endDate

string<date>

required

End date for the trend range (YYYY-MM-DD)

Response

Successfully retrieved incoming email trends for top client domains

message

string

Example:

""

data

object

Show child attributes

Clients with Lowest Resolution Rates Client Domain Response Times

​Request

​Headers

​Path Parameters

​Parameter Format

​Response

​200 OK - Successfully retrieved incoming email trends for top client domains

​401 Unauthorized

​500 Internal Server Error

​Example

​Data Structure

​Labels Array

​Series Array

​Data Alignment

​Use Cases

​Analysis Examples

​Domain Growth Analysis

​Peak Day Identification

​Correlation Analysis

​Visualization Examples

​Multi-Line Chart

​Stacked Area Chart

​Best Practices

​Performance Considerations

​Related Endpoints

​Notes

Authorizations

Path Parameters

Response

Request

Headers

Path Parameters

Parameter Format

Response

200 OK - Successfully retrieved incoming email trends for top client domains

401 Unauthorized

500 Internal Server Error

Example

Data Structure

Labels Array

Series Array

Data Alignment

Use Cases

Analysis Examples

Domain Growth Analysis

Peak Day Identification

Correlation Analysis

Visualization Examples

Multi-Line Chart

Stacked Area Chart

Best Practices

Performance Considerations

Related Endpoints

Notes