Merge pull request #34 from mailsac/add_reading_mail_docs

Add reading mail docs

.gitignore

@@ -63,8 +63,6 @@ typings/
 # dotenv environment variables file
 .env
 
->>>>>>> 4180f6db77af84b004621f12f201de8f77d8676b
-
 #sphinx
 _build/
 

index.rst

@@ -51,7 +51,8 @@ Table of Contents
    services/email_hosting
    services/webhook
    services/forwarding/forwarding
-   services/sending_mail/sendingmail
+   services/sending_mail/sending_mail
+   services/reading_mail/reading_mail
    services/mailredirect
    services/slack_webhook/slack_webhook
    services/custom_domains/custom_domains

services/reading_mail/reading_mail.js

@@ -0,0 +1,22 @@
+const superagent = require('superagent')
+const mailsac_api_key = 'YOUR_API_KEY_HERE'
+
+superagent
+  .get('https://mailsac.com/api/addresses/calendartrinity@mailsac.com/messages')
+  .set('Mailsac-Key', mailsac_api_key)
+  .then((messages) => {
+      messageId = messages.body[0]._id
+      superagent
+          .get('https://mailsac.com/api/text/calendartrinity@mailsac.com/' + messageId)
+          .set('Mailsac-Key', mailsac_api_key)
+              .then((messageText) => {
+                  console.log(messageText.text)
+              })
+  })
+  .catch(err => {
+      console.log(err.message)
+  })
+
+/*
+Dogtreats are good!
+*/

services/reading_mail/reading_mail.py

@@ -0,0 +1,14 @@
+import requests
+from pprint import pprint
+
+headers = {'Mailsac-Key': 'YOUR_API_KEY_HERE'}
+url = 'https://mailsac.com/api/addresses/calendartrinity@mailsac.com/messages'
+r = requests.get(url, headers=headers)
+message_id =  r.json()[0]['_id']
+url = 'https://mailsac.com/api/text/calendartrinity@mailsac.com/' + message_id
+r = requests.get(url, headers=headers)
+pprint(r.text)
+
+'''
+'Dogteats are good!'
+'''

services/reading_mail/reading_mail.rst

@@ -0,0 +1,140 @@
+.. _`Mailsac Website`: https://mailsac.com
+.. _Unified Inbox: https://mailsac.com/app
+.. _Dashboard: https://mailsac.com/dashboard
+.. _REST API: https://mailsac.com/api
+.. _API Key: https://mailsac.com/api-keys
+
+.. _doc_reading_mail:
+
+Reading Mail
+============
+
+There are several ways for to view email messages using Mailsac
+
+- :ref:`Inbox View <sec_inbox_view>`
+- :ref:`Unified Inbox <sec_unified_inbox>`
+- :ref:`REST API <sec_reading_mail_rest_api>`
+- :ref:`SMTP <sec_reading_mail_smtp>`
+
+.. _sec_read_mail_message:
+
+Read a Mail Message
+-------------------
+
+.. tabs::
+   .. tab:: Mailsac Website
+
+      .. figure:: inbox_view_reading_mail.gif
+
+         View Emails from the main page of the `Mailsac Website`_
+
+   .. tab:: Unified Inbox
+
+      .. figure:: unified_inbox_reading_mail.gif
+
+         Read using the `Unified Inbox`_
+
+   .. tab:: curl
+
+       .. literalinclude:: reading_mail.sh
+          :language: bash
+          :caption: Read using curl. Requires
+                    `JQ <https://stedolan.github.io/jq/>`_
+
+   .. tab:: Node.js Javascript 
+
+       .. literalinclude:: reading_mail.js
+          :language: javascript
+          :caption: Read using Node.js. requires
+                    :code:`npm install superagent`
+
+   .. tab:: Python
+
+       .. literalinclude:: reading_mail.py
+          :language: python
+          :caption: Read using Python
+
+.. _sec_inbox_view:
+
+Inbox View
+----------
+
+Enter the email address of the Inbox to be viewed in this box on the main page of
+the `Mailsac Website`_
+
+.. figure:: main_page_inbox.png
+
+An Inbox can be viewed by entering the URL for the Inbox in a browser address
+bar. The URL to view an Inbox always follows the format
+:code:`https://mailsac.com/inbox/EMAIL_ADDRESS`
+
+Any :ref:`non-private email address <doc_private_addresses>` can be viewed
+without creating an account. To view the images and links of a message a Mailsac
+account must be used. A free account can be created from the
+`sign-up page <https://mailsac.com/register>`_
+
+.. _sec_unified_inbox:
+
+Unified Inbox
+-------------
+
+The `Unified Inbox`_ provides a way to view the mail of all
+:ref:`private addresses <doc_private_addresses>` for the logged in Mailsac account.
+
+.. figure:: unified_inbox_view.png
+
+The `Unified Inbox`_ is useful for managing multiple email addresses. 
+
+.. _sec_reading_mail_rest_api:
+
+REST API
+--------
+
+The REST API is the preferred method for reading messages programmattically.
+The :code:`/api/addresses/:email/messages` and
+:code:`/api/text/:email/:messageId` endpoints documented in the
+`REST API documentation <https://mailsac.com/docs/api/#email-messages-api>`_.
+
+1. Generate an API by selecting `API Keys <https://mailsac.com/api-keys>`_ from
+   the Dashboard_.
+2. Send email using curl or your favorite HTTP library. :ref:`Code Examples <sec_read_mail_message>`
+
+.. _sec_reading_mail_smtp:
+
+Reading with POP3
+-----------------
+
+Reading via POP3 allows email clients to read email.
+
+**Authentication**
+
+POP3 uses a username and password for authentication. The API key or SMTP Key
+for your account can be used to read from any of your :ref:`private addresses
+<doc_private_addresses>`. Alternatively, you can use a per private address SMTP
+password. The per private address SMTP password can be set through using the
+Dashboard_ -> *Manage Email Addresses* -> Select the
+*POP/SMTP* button next to the email address -> Select *Set New Password*
+
+    .. figure:: ../sending_mail/pop_smtp_set_password.png
+        :align: center
+        :width: 400px
+
+**Email Client Configuration**
+
+Configure your email client (Gmail, Apple mail, Thunberbird, Outlook, iPhone,
+etc) using these POP3 settings:
+
++-----------------------+-------------------------------------------------------+
+| **Hostname / Server** | poppy.mailsac.com                                     |
++-----------------------+-------------------------------------------------------+
+| **Email Address**     | Private email address                                 |
++-----------------------+-------------------------------------------------------+
+| **Username**          + Private email address                                 |
++-----------------------+-------------------------------------------------------+
+| **Password**          | `API Key`_ or SMTP Key                                |
++-----------------------+-------------------------------------------------------+
+| **Port**              | 110                                                   |
++-----------------------+-------------------------------------------------------+
+| **Auth Settings**     | Password / allow plain / insecure                     |
++-----------------------+-------------------------------------------------------+
+

services/reading_mail/reading_mail.sh

@@ -0,0 +1,8 @@
+curl -s -H "Mailsac-Key: YOUR_API_KEY_HERE" \
+    -X GET https://mailsac.com/api/addresses/calendartrinity@mailsac.com/messages \
+    | jq .[0]._id | \
+    xargs -I {} curl -H "Mailsac-Key: YOUR_API_KEY_HERE" \
+    -X GET https://mailsac.com/api/text/calendartrinity@mailsac.com/{}
+
+# curl output
+Dogtreats are good!