Stats

Mailgun collects many different events and generates event statistics which are available in your Control Panel. This data is also available via an API.

GET /<domain>/stats

Returns a list of event stat items. Each record represents counts for one event per one day.

Parameter	Description
limit	Maximum number of records to return. (100 by default)
skip	Number of records to skip. (0 by default)
event	Name of the event to receive the stats for. Note that you can specify this parameter multiple times to fetch stats for several events at the same time (see example below)

Examples

Get stats for ‘open’ and ‘sent’ events sorted by date:

def get_stats
  url_params = Multimap.new
  url_params[:skip] = 1
  url_params[:limit] = 2
  url_params[:event] = "sent"
  url_params[:event] = "opened"
  query_string = url_params.collect {|k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}"}.
    join("&")
  RestClient.get "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/stats?#{query_string}"
end

Response:

{
  "total_count": 80,
  "items": [
    {
      "total_count": 9,
      "created_at": "Thu, 02 Feb 2012 00:00:00 GMT",
      "tags": {},
      "id": "4f29e61e4d532a3a823d419d",
      "event": "sent"
    },
    {
      "total_count": 1,
      "created_at": "Thu, 02 Feb 2012 00:00:00 GMT",
      "tags": {},
      "id": "4f2ad1e84d532a3a823d5e92",
      "event": "opened"
    }
  ]
}

Get stats for ‘open’ and ‘sent’ events sorted by date:

public static ClientResponse GetStats() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/stats");
       MultivaluedMapImpl queryParams = new MultivaluedMapImpl();
       queryParams.add("event", "sent");
       queryParams.add("event", "opened");
       queryParams.add("skip", 1);
       queryParams.add("limit", 2);
       return webResource.queryParams(queryParams).get(ClientResponse.class);
}

Response:

{
  "total_count": 29,
  "items": [
    {
      "total_count": 1,
      "created_at": "Sat, 12 Nov 2011 00:00:00 GMT",
      "tags": {},
      "id": "4ebec0166c5f6b0f93598f4d",
      "event": "sent"
    },
    {
      "total_count": 192,
      "created_at": "Fri, 11 Nov 2011 00:00:00 GMT",
      "tags": {
        "september_newsletter": 17,
        "newsletters": 17
      },
      "id": "4ebd0aa96c5f6b0f93597659",
      "event": "sent"
    }
  ]
}

Get stats for ‘open’ and ‘sent’ events sorted by date:

function get_stats() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/stats',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $data = array('event' => array('sent', 'opened'),
                'skip' => 1,
                'limit' => 1);
  $dataString = '';
  foreach ($data as $key => $val) {
    if (is_array($val)) {
      foreach ($val as $v) {
        $dataString .= urlencode($key).'='.urlencode($v).'&';
      }
    } else {
      $dataString .= urlencode($key).'='.urlencode($val).'&';
    }
  }
  $request->setQueryData(substr($dataString, 0, -1));
  $request->send();
  return $request;
}

Response:

{
  "total_count": 30,
  "items": [
    {
      "total_count": 52,
      "created_at": "Mon, 14 Nov 2011 00:00:00 GMT",
      "tags": {
        "september_newsletter": 5,
        "newsletters": 5
      },
      "id": "4ec153086c5f6b0f9359a8d8",
      "event": "sent"
    }
  ]
}

Get stats for ‘open’ and ‘sent’ events sorted by date:

def get_stats():
    r = requests.\
        get(("https://api.mailgun.net/v2/samples.mailgun.org/"
             "stats"),
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
            params={
                "event": ["sent", "opened"],
                "skip": 1,
                "limit": 2
                }
            )
    return r

Response:

{
  "total_count": 87,
  "items": [
    {
      "total_count": 178,
      "created_at": "Mon, 06 Feb 2012 00:00:00 GMT",
      "tags": {
        "september_newsletter": 15,
        "newsletters": 15
      },
      "id": "4f2f82b94d532a3a82400d00",
      "event": "sent"
    },
    {
      "total_count": 3,
      "created_at": "Mon, 06 Feb 2012 00:00:00 GMT",
      "tags": {},
      "id": "4f2f7bf04d532a3a82400c6b",
      "event": "opened"
    }
  ]
}

Get stats for ‘open’ and ‘sent’ events sorted by date:

public static RestResponse GetStats() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/stats";
       request.AddParameter("event", "sent");
       request.AddParameter("event", "opened");
       request.AddParameter("skip", 1);
       request.AddParameter("limit", 2);
       return client.Execute(request);
}

Response:

{
  "total_count": 30,
  "items": [
    {
      "total_count": 52,
      "created_at": "Mon, 14 Nov 2011 00:00:00 GMT",
      "tags": {
        "september_newsletter": 5,
        "newsletters": 5
      },
      "id": "4ec153086c5f6b0f9359a8d8",
      "event": "sent"
    },
    {
      "total_count": 1,
      "created_at": "Sat, 12 Nov 2011 00:00:00 GMT",
      "tags": {},
      "id": "4ebec0166c5f6b0f93598f4d",
      "event": "sent"
    }
  ]
}

Get stats for ‘open’ and ‘sent’ events sorted by date:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -G \
    https://api.mailgun.net/v2/samples.mailgun.org/stats \
    -d event='sent'\
    -d event='opened' \
    -d skip=1 \
    -d limit=2

Response:

{
  "total_count": 95,
  "items": [
      {
          "event": "sent",
          "total_count": 16,
          "created_at": "Tue, 14 Feb 2012 00:00:00 GMT",
          "id": "4f39f7c56addaa3e1966714d",
          "tags": {}
      },
      {
          "event": "sent",
          "total_count": 1,
          "created_at": "Mon, 13 Feb 2012 00:00:00 GMT",
          "id": "4f38f9ac6addaa3e1966335e",
          "tags": {}
      }
  ]
}