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 hour
  • d - a day
  • m - 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
        }
      },
    }
  ]
}