Stats¶
Mailgun collects many different events and generates event statistics which are available in your Control Panel. This data is also available via our stats API endpoint. The stats endpoint is available at:
v3/<domain>/stats
The statistics are calculated in hourly, daily and monthly resolution in UTC timezone.
GET /<domain>/stats/total
Returns total stats for a given domain.
Parameter | Description |
---|---|
event | The type of the event. For a complete list of all events written to the log see the Event Types table below. (Required) |
start | The starting time. Should be in RFC 2822#page-14 or unix epoch format. Default: 7 days from the current time. |
end | The ending date. Should be in RFC 2822#page-14 or unix epoch format. Default: current time. |
resolution | Can be either hour , day or month . Default: day |
duration | Period of time with resoluton encoded. See Duration for more info. If provided, overwrites the start date. |
Data Retention¶
The following retention policy is applied to the statistics:
- Hourly stats are preserved for two months.
- Daily stats are preserved for a year.
- Monthly stats are stored throughout the lifespan of the domain.
Duration¶
Duration is a string that represents a period of time with some resolution.
It has a format [0-9]+[m,d,h]
where
h
- an hourd
- a daym
- a month
Examples:
- 24h - a period of 24 hours (a day) with hourly resolution
- 1d - a period of 1 day with daily resolution
- 2m - a period of 2 months with monthly resolution
Event Types¶
Mailgun tracks all of the events that occur throughout the system. Below are listed the events that you can retrieve using this API.
Event Type | Description |
---|---|
accepted | Mailgun accepted the request to send/forward the email and the message has been placed in queue. |
delivered | Mailgun sent the email and it was accepted by the recipient email server. |
failed | Mailgun could not deliver the email to the recipient email server. |
opened | The email recipient opened the email and enabled image viewing. Open tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org. |
clicked | The email recipient clicked on a link in the email. Click tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org. |
unsubscribed | The email recipient clicked on the unsubscribe link. Unsubscribe tracking must be enabled in the Mailgun control panel. |
complained | The email recipient clicked on the spam complaint button within their email client. Feedback loops enable the notification to be received by Mailgun. |
stored | Mailgun has stored an incoming message |
Group¶
Allows for grouping metrics by group type.
- total
- time
- day
- month
- domain
- ip
- provider
- tag
- country
- subaccount
- ip_pool
GET /v3/stats/filter?event=delivered&group=provider
Filter by Subaccount¶
Use the subaccount ID to filter stats to a specific subaccount
GET /v3/stats/filter?event=delivered&filter=subaccount:<Subaccount ID>
Filter by IP Pool¶
Use the IP Pool ID to filter stats to a specific IP Pool
GET /v3/stats/filter?event=delivered&filter=ip_pool:<IP Pool ID>
Examples¶
Get stats for ‘accepted’, ‘delivered’, and ‘failed’ events for the past month:
curl -s --user 'api:YOUR_API_KEY' -G \
https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/stats/total \
-d event='accepted' \
-d event='delivered' \
-d event='failed' \
-d duration='1m'
import java.util.List;
import com.mailgun.api.v3.MailgunStatisticsApi;
import com.mailgun.enums.Duration;
import com.mailgun.enums.ResolutionPeriod;
import com.mailgun.enums.StatsEventType;
import com.mailgun.model.StatisticsOptions;
import com.mailgun.model.stats.StatsResult;
// ...
public StatsResult getStats() {
MailgunStatisticsApi mailgunStatisticsApi = MailgunClient.config(API_KEY)
.createApi(MailgunStatisticsApi.class);
StatisticsOptions statsOptions = StatisticsOptions.builder()
.event(List.of(StatsEventType.ACCEPTED, StatsEventType.DELIVERED))
.resolution(ResolutionPeriod.MONTH)
.duration(3, Duration.MONTH)
.build();
return mailgunStatisticsApi.getDomainStats(YOUR_DOMAIN_NAME, statsOptions);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;
# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain = 'YOUR_DOMAIN_NAME';
# Define your Event types
$params = array(
"event" => ["accepted", "delivered", "failed", "complained"]
);
$response = $mgClient->stats()->total($domain, $params);
def get_stats():
return requests.get(
"https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/stats/total",
auth=("api", "YOUR_API_KEY"),
params={"event": ["accepted", "delivered", "failed"],
"duration": "1m"})
def get_stats
url_params = {}
url_params[:duration] = "1m"
url_params[:event] = []
url_params[:event] << "accepted"
url_params[:event] << "delivered"
url_params[:event] << "failed"
query_string = url_params.collect {|k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}"}.
join("&")
RestClient.get "https://api:YOUR_API_KEY"\
"@api.mailgun.net/v3/YOUR_DOMAIN_NAME/stats/total?#{query_string}"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;
public class GetStatsChunk
{
public static void Main (string[] args)
{
Console.WriteLine (GetStats ().Content.ToString ());
}
public static IRestResponse GetStats ()
{
RestClient client = new RestClient ();
client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
client.Authenticator =
new HttpBasicAuthenticator ("api",
"YOUR_API_KEY");
RestRequest request = new RestRequest ();
request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
request.Resource = "{domain}/stats/total";
request.AddParameter ("event", "accepted");
request.AddParameter ("event", "delivered");
request.AddParameter ("event", "failed");
request.AddParameter ("duration", "1m");
return client.Execute (request);
}
}
import (
"context"
"github.com/mailgun/mailgun-go/v3"
"time"
)
func GetStats(domain, apiKey string) ([]mailgun.Stats, error) {
mg := mailgun.NewMailgun(domain, apiKey)
ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
defer cancel()
return mg.GetStats(ctx, []string{"accepted", "delivered", "failed"}, &mailgun.GetStatOptions{
Duration: "1m",
})
}
const DOMAIN = 'YOUR_DOMAIN_NAME';
import formData from 'form-data';
import Mailgun from 'mailgun.js';
const mailgun = new Mailgun(formData);
const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
try {
const statsForDomain = await client.stats.getDomain(DOMAIN,{ 'event': ['accepted', 'delivered', 'failed'], 'duration': '1m'})
console.log('statsForDomain', statsForDomain);
} catch (error) {
console.error(error);
}
})();
Sample response:
{
"end": "Fri, 01 Apr 2012 00:00:00 UTC",
"resolution": "month",
"start": "Tue, 14 Feb 2012 00:00:00 UTC",
"stats": [
{
"time": "Tue, 14 Feb 2012 00:00:00 UTC",
"accepted": {
"outgoing": 10, // authenticated
"incoming": 5, // unauthenticated
"total": 15
},
"delivered": {
"smtp": 15, // delivered over SMTP
"http": 5, // delivered over HTTP
"total": 20
},
"failed": {
"permanent": {
"bounce": 4,
"delayed-bounce": 1,
"suppress-bounce": 1, // recipients previously bounced
"suppress-unsubscribe": 2, // recipients previously unsubscribed
"suppress-complaint": 3, // recipients previously complained
"total": 10 // failed permanently and dropped
},
"temporary": {
"espblock": 1, // failed temporary due to ESP block, will be retried
"total": 1
}
},
}
]
}