Skip to main content

Analyse hops taken by an Email to reach you. Get structured information about each hop - Hostnames, Protocol used, Timestamp, and Delay

Project 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
emailtrail-0.3.21.tar.gz (7.2 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page