Merge pull request #148 from sendgrid/email_activity

Stats GET endpoint

Author: thinkingserious

README.rst

@@ -276,10 +276,6 @@ Update the name of an existing API Key
 
 Unsubscribe Manager gives your recipients more control over the types of emails they want to receive by letting them opt out of messages from a certain type of email.
 
-More information_. 
-
-.. _information: https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/index.html
-
 Unsubscribe Groups
 ~~~~~~~~~~~~~~~~~~~
 
@@ -361,6 +357,17 @@ Delete an email from the global suppression list.
     email = 'example@example.com'
     status, msg = client.asm_global_suppressions.delete(email)
 
+`Global Stats`_
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Global Stats provide all of your user’s email statistics for a given date range.
+
+.. code:: python
+    start_date = '2015-10-01' # required
+    end_date = None # optional
+    aggregated_by = 'week' # optional, must be day, week or month
+    status, msg = client.stats.get(start_date, end_date, aggregated_by)
+
 SendGrid's `X-SMTPAPI`_
 -----------------------
 
@@ -592,3 +599,5 @@ Deploying
 .. _`Web API v3 endpoints`: https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html
 .. _TOX: https://testrun.org/tox/latest/
 .. _`few of the v3`: APIKeysAnchor_
+.. _`Suppression Management`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/index.html
+.. _`Global Stats`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Stats/global.html

example_v3_test.py

@@ -10,6 +10,16 @@
 
 client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
 
+start_date = '2015-10-01'
+end_date = None
+aggregated_by = 'week' # must be day, week or month
+status, msg = client.stats.get(
+                start_date=start_date, 
+                end_date=end_date, 
+                aggregated_by=aggregated_by)
+print status
+print msg
+
 """
 email = 'example@example.com'
 status, msg = client.asm_global_suppressions.delete(email)

sendgrid/client.py

@@ -16,6 +16,7 @@
 from .resources.asm_suppressions import ASMSuppressions
 from .resources.asm_global_suppressions import ASMGlobalSuppressions
 from .resources.suppressions import Suppressions
+from .resources.stats import Stats
 
 class SendGridAPIClient(object):
 
@@ -40,6 +41,7 @@ def __init__(self, apikey, **opts):
         self.asm_suppressions = ASMSuppressions(self)
         self.asm_global_suppressions = ASMGlobalSuppressions(self)
         self.suppressions = Suppressions(self)
+        self.stats = Stats(self)
 
     @property
     def apikey(self):

sendgrid/resources/stats.py

@@ -0,0 +1,47 @@
+try:
+    from urllib.parse import urlencode
+except ImportError:  # Python 2
+    from urllib import urlencode
+    
+class Stats(object):
+    """Global Stats provide all of your user's email statistics for a given date range."""
+    
+    def __init__(self, client, **opts):
+        """
+        Constructs SendGrid Stats object.
+        
+        See https://sendgrid.com/docs/API_Reference/Web_API_v3/Stats/global.html
+        """
+        self._name = None
+        self._base_endpoint = "/v3/stats?"
+        self._endpoint = "/v3/stats?"
+        self._client = client
+
+    @property
+    def base_endpoint(self):
+        return self._base_endpoint
+
+    @property
+    def endpoint(self):
+        endpoint = self._endpoint
+        return endpoint
+
+    @endpoint.setter
+    def endpoint(self, value):
+        self._endpoint = value
+
+    @property
+    def client(self):
+        return self._client
+        
+    # Gets email statistics.
+    def get(self, start_date, end_date=None, aggregated_by=None):
+        # Required
+        args = {'start_date': start_date}
+        # Optional arguements
+        if end_date: 
+            args['end_date'] = end_date
+        if aggregated_by:
+            args['aggregated_by'] = aggregated_by
+        self._endpoint = self._base_endpoint + urlencode(args)
+        return self.client.get(self)

test/test_stats.py

@@ -0,0 +1,42 @@
+from .base_test import BaseTest, MockSendGridAPIClientRequest
+import os
+try:
+    import unittest2 as unittest
+except ImportError:
+    import unittest
+try:
+    from StringIO import StringIO
+except ImportError:  # Python 3
+    from io import StringIO
+
+import sendgrid
+from sendgrid.client import SendGridAPIClient
+from sendgrid.version import __version__
+
+SG_KEY  = os.getenv('SG_KEY') or 'SENDGRID_APIKEY'
+
+class TestStats(unittest.TestCase):
+    def setUp(self):
+        SendGridAPIClient = MockSendGridAPIClientRequest
+        self.client = SendGridAPIClient(SG_KEY)
+        
+    def test_stats_init(self):
+        self.stats = self.client.stats
+        self.assertEqual(self.stats.base_endpoint, "/v3/stats?")
+        self.assertEqual(self.stats.endpoint, "/v3/stats?")
+        self.assertEqual(self.stats.client, self.client)
+
+    def test_stats_get(self):
+        status, msg = self.client.stats.get('2015-01-01')
+        self.assertEqual(status, 200)
+        status, msg = self.client.stats.get('2015-01-01', '2015-01-02')
+        self.assertEqual(status, 200)
+        status, msg = self.client.stats.get('2015-01-01', '2015-01-02', 'day')
+        self.assertEqual(status, 200)
+        status, msg = self.client.stats.get('2015-01-01', None, 'week')
+        self.assertEqual(status, 200)
+        status, msg = self.client.stats.get('2015-01-01', None, 'month')
+        self.assertEqual(status, 200)
+
+if __name__ == '__main__':
+    unittest.main()