diff --git a/README.rst b/README.rst index b4abb4f2f..45f996196 100644 --- a/README.rst +++ b/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 diff --git a/example_v3_test.py b/example_v3_test.py index 419bec2b7..d917d8a7e 100755 --- a/example_v3_test.py +++ b/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) diff --git a/sendgrid/client.py b/sendgrid/client.py index f16bc6cde..6b220b50c 100644 --- a/sendgrid/client.py +++ b/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): diff --git a/sendgrid/resources/stats.py b/sendgrid/resources/stats.py new file mode 100644 index 000000000..cae097825 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/test/test_stats.py b/test/test_stats.py new file mode 100644 index 000000000..7fc41af2f --- /dev/null +++ b/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() \ No newline at end of file