Analytics

With these requests, get analytics on the activity of your emails like open rate, CTR, bounce rate, and other data for a dedicated list of recipients, domain names, or even tags.

Note on data retention

Analytics data is stored for up to 6 months.

Activity data by date

Retrieve data grouped by date, based on activity, with this GET request:

GET https://api.mailersend.com/v1/analytics/date

Request parameters

Query parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`recipient_id[]`	`string`	no	Max number of recipients: 50 TBD	Not yet implemented
`date_from`	`int`	yes	Timestamp is assumed to be `UTC`. Must be lower than `date_to`.	Format: `1443651141`
`date_to`	`int`	yes	Timestamp is assumed to be `UTC`. Must be higher than `date_from`.	Format: `1443661141`
`group_by`	`string`	no	Possible options: `days`, `weeks`, `months`, `years`	Default: `days`
`tags[]`	`string[]`	no
`event[]`	`string[]`	yes	Possible types: `queued`,`sent`,`delivered`,`soft_bounced`, `hard_bounced`,`opened`,`clicked`,`unsubscribed`, `spam_complaints`,`survey_opened`, `survey_submitted`

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\ActivityAnalyticsParams;
use MailerSend\Common\Constants;

$mailersend = new MailerSend(['api_key' => 'key']);

$activityAnalyticsParams = (new ActivityAnalyticsParams(100, 101))
                    ->setDomainId('domain_id')
                    ->setGroupBy(Constants::GROUP_BY_DAYS)
                    ->setTags(['tag'])
                    ->setEvent(['sent', 'delivered']);

$mailersend->analytics->activityDataByDate($activityAnalyticsParams);

More examplesopen in new window

import 'dotenv/config';
import { ActivityEventType, MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.analytics.byDate({
  date_from: 1443651141,
  date_to: 2443651141,
  event: [ActivityEventType.CLICKED, ActivityEventType.OPENED],
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log(error.body);
});

More examplesopen in new window

from mailersend import analytics

api_key = "API key here"

mailer = analytics.NewAnalytics(api_key)

date_from = 1623073576
date_to = 1623074976
events = [
    "sent",
    "delivered",
]

# optional arguments
domain_id = "domain-id"
group_by = "days"

mailer.get_activity_by_date(date_from, date_to, events, domain_id, group_by)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	from := time.Now().Add(-24 * time.Hour).Unix()
	to := time.Now().Unix()
	domainID := "domain-id"
	events := []string{"sent", "queued", "delivered"}

	options := &mailersend.AnalyticsOptions{
		DomainID:    domainID,
		DateFrom:    from,
		DateTo:      to,
		Event:       events,
	}

	_, _, err := ms.Analytics.GetActivityByDate(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import java.util.Date;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.analytics.AnalyticsByDate;
import com.mailersend.sdk.analytics.AnalyticsByDateList;
import com.mailersend.sdk.analytics.AnalyticsList;
import com.mailersend.sdk.analytics.AnalyticsStatistic;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.util.EventTypes;

public void getAnalyticsByDate() {

    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
        Date dateFrom = new Date(); // set your from date normally
        
        AnalyticsByDateList list = ms.analytics()
                .dateFrom(dateFrom)
                .dateTo(new Date())
                .domainId(TestHelper.domainId)
                .getByDate(new String[] {EventTypes.DELIVERED, EventTypes.OPENED, EventTypes.CLICKED});
        
        System.out.println("\n\nAnalytics by date for domain:");
        for (AnalyticsByDate dayStat : list.statistics) {
            
            System.out.println(dayStat.statDate.toString());
            System.out.println(dayStat.delivered);
            System.out.println(dayStat.opened);
            System.out.println(dayStat.clicked);
                            
        }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_analytics = Mailersend::Analytics.new
ms_analytics.date(date_from: 1620643567, date_to: 1623321967, events: %w[sent queued])

More examplesopen in new window

Responses

Response key	Type	Details
`data.stats.*.date`	`timestamp`	The `date` will be at the start of the `group_by` unit (so start of day/week/month/year). Every date in the date range will be present, even if there are no events for that day.
`data.stats.*.[event]`	`int`	Every queried `event[]` will be present in the response with a default value - `0`

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "date_from": "1591228800",
    "date_to": "1591401599",
    "group_by": "days",
    "stats": [
      {
        "date": "1591228800",
        "queued": 0,
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "soft_bounced": 0,
        "hard_bounced": 0,
        "unsubscribed": 0,
        "spam_complaints": 0,
        "opened_unique": 0,
        "clicked_unique": 0,
	"survey_opened":0,
	"survey_submitted":0
      },
      {
        "date": "1591315200",
        "queued": 0,
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "soft_bounced": 0,
        "hard_bounced": 0,
        "unsubscribed": 0,
        "spam_complaints": 0,
        "opened_unique": 0,
        "clicked_unique": 0,
	"survey_opened":0,
	"survey_submitted":0
      }
    ]
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Opens by country

Retrieve data grouped by country, based on activity, with this GET request:

GET https://api.mailersend.com/v1/analytics/country

Request parameters

Query parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`recipient_id[]`	`string`	no	Max number of recipients: 50 TBD	Not yet implemented
`date_from`	`int`	yes	Timestamp is assumed to be `UTC`. Must be lower than `date_to`.	Format: `1443651141`
`date_to`	`int`	yes	Timestamp is assumed to be `UTC`. Must be higher than `date_from`.	Format: `1443661141`
`tags[]`	`string[]`	no

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
                    ->setDomainId('domain_id')
                    ->setTags(['tag']);

$mailersend->analytics->opensByCountry($opensAnalyticsParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.analytics.byCountry({
  date_from: 1443651141,
  date_to: 2443651141,
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log(error.body);
});

More examplesopen in new window

from mailersend import analytics

api_key = "API key here"

mailer = analytics.NewAnalytics(api_key)

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_country(date_from, date_to, domain_id)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	from := time.Now().Add(-24 * time.Hour).Unix()
	to := time.Now().Unix()
	domainID := "domain-id"

	options := &mailersend.AnalyticsOptions{
		DomainID: domainID,
		DateFrom: from,
		DateTo:   to,
	}

	_, _, err := ms.Analytics.GetOpensByCountry(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import java.util.Date;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.analytics.AnalyticsList;
import com.mailersend.sdk.analytics.AnalyticsStatistic;
import com.mailersend.sdk.exceptions.MailerSendException;

public void getOpensByCountry() {

    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
        Date dateFrom = new Date(); // set your from date normally
        
        AnalyticsList list = ms.analytics()
                .dateFrom(dateFrom)
                .dateTo(new Date())
                .domainId(TestHelper.domainId)
                .getOpensByCountry();
        
        System.out.println("\n\nOpens by country:");
        
        for (AnalyticsStatistic stat : list.statistics) {
            
            System.out.println(stat.name + " - " + stat.count);
        }
                
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_analytics = Mailersend::Analytics.new
ms_analytics.country(date_from: 1620643567, date_to: 1623321967)

More examplesopen in new window

Responses

Response key	Type	Details
`data.stats.*.name`	`string`	2 Letter code of the country.open in new window Will not be present if there's no data.
`data.stats.*.count`	`int`

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "date_from": 1591228800,
    "date_to": 1591401599,
    "stats": [
      {
        "name": "LT",
        "count": 2
      }
    ]
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Opens by user-agent name

Retrieve data grouped by user-agent name (browser and operating system), based on activity, with this GET request:

GET https://api.mailersend.com/v1/analytics/ua-name

Request parameters

Query parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`recipient_id[]`	`string`	no	Max number of recipients: 50 TBD	Not yet implemented
`date_from`	`int`	yes	Timestamp is assumed to be `UTC`. Must be lower than `date_to`.	Format: `1443651141`
`date_to`	`int`	yes	Timestamp is assumed to be `UTC`. Must be higher than `date_from`.	Format: `1443661141`
`tags[]`	`string[]`	no

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
                    ->setDomainId('domain_id')
                    ->setTags(['tag']);

$mailersend->analytics->opensByUserAgentName($opensAnalyticsParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.analytics.byUserAgent({
  date_from: 1443651141,
  date_to: 2443651141,
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log(error.body);
});

More examplesopen in new window

require "mailersend-ruby"

ms_analytics = Mailersend::Analytics.new
ms_analytics.ua_name(date_from: 1620643567, date_to: 1623321967)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	from := time.Now().Add(-24 * time.Hour).Unix()
	to := time.Now().Unix()
	domainID := "domain-id"

	options := &mailersend.AnalyticsOptions{
		DomainID: domainID,
		DateFrom: from,
		DateTo:   to,
	}

	_, _, err := ms.Analytics.GetOpensByUserAgent(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import java.util.Date;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.analytics.AnalyticsList;
import com.mailersend.sdk.analytics.AnalyticsStatistic;
import com.mailersend.sdk.exceptions.MailerSendException;

public void getOpensByUserAgentName() {

    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
        Date dateFrom = new Date(); // set your from date normally
        
        AnalyticsList list = ms.analytics()
                .dateFrom(dateFrom)
                .dateTo(new Date())
                .getOpensByUserAgent();
        
        System.out.println("\n\nOpens by user agent:");
        
        for (AnalyticsStatistic stat : list.statistics) {
            
            System.out.println(stat.name + " - " + stat.count);
        }
                
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

from mailersend import analytics

api_key = "API key here"

mailer = analytics.NewAnalytics(api_key)

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_user_agent(date_from, date_to, domain_id)

More examplesopen in new window

Responses

Response key	Type	Details
`data.stats.*.name`	`string`	User Agent Name. Will not be present if there's no data.
`data.stats.*.count`	`int`

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "date_from": 1591228800,
    "date_to": 1591401599,
    "stats": [
      {
        "name": "Chrome",
        "count": 2
      }
    ]
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Opens by reading environment

Retrieve data grouped by the reading environment (webmail, mobile, desktop), based on activity, with this GET request:

GET https://api.mailersend.com/v1/analytics/ua-type

Request parameters

Query parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`recipient_id[]`	`string`	no	Max number of recipients: 50 TBD	Not yet implemented
`date_from`	`int`	yes	Timestamp is assumed to be `UTC`. Must be lower than `date_to`.	Format: `1443651141`
`date_to`	`int`	yes	Timestamp is assumed to be `UTC`. Must be higher than `date_from`.	Format: `1443661141`
`tags[]`	`string[]`	no

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
                    ->setDomainId('domain_id')
                    ->setTags(['tag']);

$mailersend->analytics->opensByReadingEnvironment($opensAnalyticsParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.analytics.byReadingEnvironment({
  date_from: 1443651141,
  date_to: 2443651141,
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log(error.body);
});

More examplesopen in new window

from mailersend import analytics

api_key = "API key here"

mailer = analytics.NewAnalytics(api_key)

date_from = 1623073576
date_to = 1623074976

# optional arguments
domain_id = "domain-id"

mailer.get_opens_by_reading_environment(date_from, date_to, domain_id)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	from := time.Now().Add(-24 * time.Hour).Unix()
	to := time.Now().Unix()
	domainID := "domain-id"

	options := &mailersend.AnalyticsOptions{
		DomainID: domainID,
		DateFrom: from,
		DateTo:   to,
	}

	_, _, err := ms.Analytics.GetOpensByReadingEnvironment(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import java.util.Date;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.analytics.AnalyticsList;
import com.mailersend.sdk.analytics.AnalyticsStatistic;
import com.mailersend.sdk.exceptions.MailerSendException;

public void getOpensByUserAgentType() {

    MailerSend ms = new MailerSend();
    ms.setToken(TestHelper.validToken);
    
    try {
        
        Date dateFrom = new Date(); // set your from date normally
        
        AnalyticsList list = ms.analytics()
                .dateFrom(dateFrom)
                .dateTo(new Date())
                .getOpensByUserAgenType();
        
        System.out.println("\n\nOpens by user agent type:");
        
        for (AnalyticsStatistic stat : list.statistics) {
            
            System.out.println(stat.name + " - " + stat.count);
        }
                
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_analytics = Mailersend::Analytics.new
ms_analytics.ua_type(date_from: 1620643567, date_to: 1623321967)

More examplesopen in new window

Responses

Response key	Type	Details
`data.stats.*.name`	`string`	One of `webmail`, `mobile`,`desktop`. Will not be present if there's no data.
`data.stats.*.count`	`int`

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "date_from": 1591228800,
    "date_to": 1591401599,
    "stats": [
      {
        "name": "webmail",
        "count": 2
      },
      {
        "name": "mobile",
        "count": 2
      },
      {
        "name": "desktop",
        "count": 2
      }
    ]
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

# Analytics

# Activity data by date

# Request parameters

# Responses

# Valid

# Error

# Opens by country

# Request parameters

# Responses

# Valid

# Error

# Opens by user-agent name

# Request parameters

# Responses

# Valid

# Error

# Opens by reading environment

# Request parameters

# Responses

# Valid

# Error

Analytics

Activity data by date

Request parameters

Responses

Valid

Error

Opens by country

Request parameters

Responses

Valid

Error

Opens by user-agent name

Request parameters

Responses

Valid

Error

Opens by reading environment

Request parameters

Responses

Valid

Error