Metadata-Version: 1.0
Name: emailtrail
Version: 0.3.21
Summary: Analyse hops taken by an Email to reach you. Get structured information about each hop - Hostnames, Protocol used, Timestamp, and Delay
Home-page: https://github.com/akshayKMR/emailtrail
Author: Akshay Kumar
Author-email: akshay.kmr4321@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: .. raw:: html
        
           <h2 align="center">
        
        EmailTrail
        
        .. raw:: html
        
           </h2>
        
        .. raw:: html
        
           <p align="center">
        
        .. raw:: html
        
           <!-- <img alt="logo" title="logo" src="http://i.imgur.com/VShxJHs.png" width="450"> -->
        
        .. raw:: html
        
           </p>
        
        |Travis branch| |PRs Welcome|
        
        .. raw:: html
        
           <p>
        
        Analyse hops taken by an Email to reach you. Get structured information
        about each hop - Hostnames, Protocol used, Timestamp, and Delay.
        
        .. raw:: html
        
           </p>
        
        **In your project:** ``pip install emailtrail`` or if you use
        `pipenv <http://pipenv.org/>`__ like me ``pipenv install emailtrail``
        
        .. raw:: html
        
           <!-- START doctoc generated TOC please keep comment here to allow auto update -->
        
        .. raw:: html
        
           <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
        
        Table of Contents
        -----------------
        
        -  `Usage <#usage>`__
        -  `Caveats <#caveats>`__
        -  `Contributing <#contributing>`__
        -  `Miscellaneous <#miscellaneous>`__
        
        .. raw:: html
        
           <!-- END doctoc generated TOC please keep comment here to allow auto update -->
        
        Usage
        -----
        
        We can analyse an email source or raw headers
        
        .. code:: python
        
            email = """
            Delivered-To: money@capitalism.com
            Received: by 10.129.52.209 with SMTP id b200csp1430876ywa;
                    Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
            X-Received: by 10.31.153.20 with SMTP id b20mr6116862vke.110.1507623422746;
                    Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
            Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65])
                    by mx.google.com with SMTPS id b31sor1345013uaa.124.2017.10.10.01.17.02
                    for <money@capitalism.com>
                    (Google Transport Security);
                    Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
            Received-SPF: pass (google.com: domain of bags@test_email.ua.edu designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65;
            X-Received: by 10.176.85.196 with SMTP id w4mr6874179uaa.75.1507623422198; Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
            MIME-Version: 1.0
            Received: by 10.103.79.86 with HTTP; Tue, 10 Oct 2017 01:17:01 -0700 (PDT)
            From: Mr. Money Bags <bags@moneyrules.com>
            Date: Tue, 10 Oct 2017 01:17:01 -0700
            Subject:
            To: money@capitalism.com;
            Content-Type: text/plain; charset="UTF-8"
            Bcc: satan@wallstreet.com
        
            A business opportunity awaits
            """
        
        Lets analyse it
        ^^^^^^^^^^^^^^^
        
        .. code:: python
        
            import emailtrail
            emailtrail.analyse(email)
        
        .. code:: python
        
            {
              'To': u'money@capitalism.com;',
              'From': u'Mr. Money Bags <bags@moneyrules.com>',
              'Bcc': u'satan@wallstreet.com',
              'Cc': u'None',
              'total_delay': 1,
              'trail': [
                {
                  'delay': 0,
                  'from': '',
                  'protocol': 'HTTP',
                  'receivedBy': '10.103.79.86',
                  'timestamp': 1507623421
                },
                {
                  'delay': 1,
                  'from': 'mail-sor-f65.google.com',
                  'protocol': 'SMTPS',
                  'receivedBy': 'mx.google.com',
                  'timestamp': 1507623422
                },
                {
                  'delay': 0,
                  'from': '',
                  'protocol': 'SMTP',
                  'receivedBy': '10.129.52.209',
                  'timestamp': 1507623422
                }
              ]
            }
        
        The analyse function returns a python dictionary. The trail shows the
        email hops sorted in chronological order. Each intermediary email server
        adds a ``Received`` header to the mail, from which the module parses the
        following information:
        
        -  ``protocol`` : e.g HTTP, SMTP etc.
        -  ``from`` : The name the sending computer gave for itself
        -  ``receivedBy``: The receiving computers name
        -  ``timestamp`` : Unix epoch
        
        An empty string value is set for fields which couldn’t be determined. -
        ``delay``: The delay (in seconds) is computed by taking the difference
        of two consecutive hops. In above example there was a delay of ``1 sec``
        from ``10.103.79.86`` to ``mx.google.com``
        
        Analysing a single ``Received`` header
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        .. code:: python
        
            >>> header = """from mail-vk0-x233.google.com (mail-vk0-x233.google.com. [2607:f8b0:400c:c05::233])\n        by mx.google.com with ESMTPS id d124si110912930vka.142.2016.01.12.10.20.45\n        for <support@peacedojo.com>\n        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);\n        Wed, 16 Dec 2015 16:34:34 -0600 """
        
            >>> from emailtrail import analyse_hop, extract_protocol, extract_from_label, extract_received_by_label, extract_timestamp
        
            >>> extract_protocol(header)
            "ESMTPS"
        
            >>> extract_from_label(header)
            "mail-vk0-x233.google.com"
        
            >>> extract_received_by_label(header)
            "mx.google.com"
        
            >>> extract_timestamp(header)
            1450305274
        
            >>> analyse_hop(header)
            {
                "from": "mail-vk0-x233.google.com",
                "receivedBy": "mx.google.com",
                "protocol": "ESMTPS",
                "timestamp": 1450305274
            }
        
        Caveats
        ~~~~~~~
        
        -  Sometimes during delay calculation the timestamp difference may be
           negative. It’s not possible for a server to recieve the email before
           previous one, It means that either one or both of the servers clocks
           are off. We assume a delay of ``0`` for this hop.
        
        Contributing
        ------------
        
        emailtrail uses `pipenv <http://pipenv.org/>`__ for managing virtual env
        and package versions. - Fork the repo and clone it. - In project root:
        ``pipenv install --dev``. This installs packages required for testing
        and linting - Jump into your virutal env: ``pipenv shell`` - Running
        tests: ``pytest`` - If you want to understand the code, read the test
        cases first. - Make your changes -> Pass the tests -> Push to your
        branch -> Create pull request -> Profit ??
        
        Miscellaneous
        ^^^^^^^^^^^^^
        
        In the middle of developing this module, I switched to TDD. Albeit slow
        for a first timer initially, It proved to be a very effective approach
        later on. - Forces you to think how to structure your code. - Less
        coupling, small functions with minimal to none side effects, well
        defined interfaces. - Confidence in refactoring code quickly. (Everyone
        loves it when their investments pay off)
        
        .. |Travis branch| image:: https://img.shields.io/travis/akshayKMR/emailtrail/master.svg?style=flat-square
           :target: https://travis-ci.org/akshayKMR/emailtrail
        .. |PRs Welcome| image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
           :target: http://makeapullrequest.com
        
Platform: UNKNOWN
