Merge pull request #1 from mailsac/readthedocs

Readthedocs

.gitignore

@@ -64,3 +64,10 @@ typings/
 .env
 
 >>>>>>> 4180f6db77af84b004621f12f201de8f77d8676b
+
+#sphinx
+_build/
+
+#ignore vim swp files
+*.swp
+*.swo

LICENSE

@@ -1,6 +1,6 @@
-MIT License
+The MIT License
 
-Copyright (c) 2018 Mailsac
+Copyright (c) 2018 Michael Mayer and Jeff Parrish
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = mailsac-examples
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -1,36 +1,28 @@
-# Mailsac API Examples
+# Mailsac-Examples
+This repository is the documentation for Mailsac. It includes examples, service
+information, privacy policy, and terms of services.
 
-This repository contains examples for integrating with the
-[Mailsac API](https://mailsac.com/docs/api). The examples are written using
-[Node.js](https://nodejs.org/en/download/) which must be setup first. You should
-install at least Node version 8.
+## Build Instructions
+These documents are published to docs.mailsac.com, they can be built locally
+for testing purposes.
 
-You will also need a [Mailsac API key](https://mailsac.com/api-keys).
+1. Clone this repo
+   `git clone https://github.com/mailsac/mailsac-examples.git`
 
-## Getting Started
+2. Install sphinx
+   `pip install Sphinx`
+   `pip install sphinx_rtd_theme`
 
-Clone this repository and navigate to the directory:
+3. Change directories to the cloned repo
+   `cd mailsac-examples`
 
-```bash
-git clone https://github.com/mailsac/mailsac-examples
-cd mailsac-examples
-```
+4. Run build script
+   `make html`
 
-Now that you are inside the `mailsac-examples` folder and have Node.js installed,
-running an example can be done like this:
+5. Build results can be found in `_build/html/`
 
-```bash
-MAILSAC_KEY=your_api_key_goes_here node validate-single-email asdf@mailsac.com
-```
-*(replace `your_api_key_goes_here` with
-your key from https://mailsac.com/api-keys)*
+6. Optional - run a server to view the html output.
+    `npm install http-server -g`
+    `http-server _build/html`
 
-## Troubleshooting
-
-Each example has slightly different parameters, and should print what is missing
-if you do not supply an expected argument. If you have trouble, try opening
-the script up and looking at the usage of `process.argv`.
-
-## License
-
-MIT
+Copyright © 2018 by Michael Mayer and Jeff Parrish

_static/custom.css

@@ -0,0 +1,4 @@
+/* provides a red start on services/mailstorage.rst */
+.red {
+        color: red;
+}

_templates/layout.html

@@ -0,0 +1,21 @@
+{% extends "!layout.html" %}
+  {% block extrahead %} {{ super() }}
+
+    <style type="text/css">
+      /* Sidebar header (and topbar for mobile) */
+      .wy-side-nav-search, .wy-nav-top {
+        background: #EB649C !important;
+      }
+
+      h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
+          font-family: 'Arial', 'Helvetica', sans-serif !important;
+          color: #EB649C !important;
+      }
+
+      /* needed to make a red star */
+      .red {
+        color: red;
+      }
+    </style>
+
+  {% endblock %}

about/contact_and_support.rst

@@ -0,0 +1,35 @@
+.. _contact_and_support:
+
+Contact and Support
+===================
+
+Feature Requests
+----------------
+
+To discuss new ideas and features, visit the `feature discussion forum <https://community.mailsac.com/forums/forum/feature-requests/>`_.
+
+General Help
+------------
+
+Browse our `documentation <https://docs.mailsac.com>`_ and `forums <https://community.mailsac.com/forums/>`_.
+
+Mail Not Received
+-----------------
+
+Read about mail not received on the :ref:`#hy-weren-t-my-messages-received`.
+
+Paying Customers - Email and API Support
+----------------------------------------
+
+For service setup issues, billing questions, sales contact **support@team.mailsac.com**.
+
+Indicate your account **username** and the email address (if different from the email you are sending from).
+
+For **API support** we encourage you to post to the `Developers and API forum <https://community.mailsac.com/forums/forum/api/>`_ so
+your solution can be shared with other developers.
+
+Support Hours
+-------------
+
+We answer support requests during business hours, USA West Coast Pacific Time (PDT/PST)
+

about/faq.rst

@@ -0,0 +1,75 @@
+.. _faq:
+
+FAQ
+===
+
+Where are my email attachments?
+-------------------------------
+
+You must `download the message or parse it yourself <https://community.mailsac.com/docs/email-attachments/>`_.
+
+Why would I use Mailsac?
+------------------------
+Any time you need a temporary email address, just make one up@mailsac.com.
+
+If you need to test your email system, send it to mailsac.com - even for a custom domain.
+
+Other uses:
+
+* if you need an email address, but do not want to receive spam in your personal inbox
+* use it for sign ups on web sites that force you to login
+* give it out to strangers
+* use it to collaborate for projects
+* send mail to Mailsac for testing purposes
+* use it when you (legally) want to receive email without disclosing your identity
+* it is perfect if you want an email address or multiple addresses and do not want to sign up for them
+* comment on blogs without creating an account
+* as a developer, to test that your application is sending email
+
+Why weren't my messages received?
+---------------------------------
+
+There are many reasons messages may not be received by Mailsac.
+
+1. The sender blocks traffic to disposable email providers like Mailsac. This is
+   common with email signups or email verifications. People running websites do
+   not want a bunch of spam accounts.
+2. Large message size. Mailsac only supports messages up to about 2 MB.
+3. Throttling. Non-paying customers can be throttled for sending too much. We
+   are happy to lift this for paying customers. Usually, it is easiest for us to
+   lift it on your `Verified Domain <https://mailsac.com/domains>`_.
+
+In all cases, if you contact support, we can help you work around these
+problems. Either by hosting your own instance of Mailsac, contacting  us for
+help, or moving you to a separate inbound or outbound IP.
+
+
+Can I use Mailsac for testing purposes?
+---------------------------------------
+Absolutely!
+
+We love to hear from developers that use Mailsac - contact us anytime.
+
+.. tip:: support@team.mailsac.com
+
+If you expect to send more than a few messages per minute, you might get throttled. Contact us about 
+reducing throttling, or setup a Verified Domain, or buy an API key.
+
+
+How long is email saved?
+------------------------
+
+Email messages are saved for somewhere between three days and 1 week or more, sometimes less. No guarantees!
+
+If you are logged in and star a message, it will not be recycled until you unstar it. Or if you have made it private, messages will be kept up to your storage limit.
+
+Can other people see messages that I starred?
+---------------------------------------------
+Nope. Only you can see them when you are logged in.
+
+
+How do I reply to my Mailsac emails?
+------------------------------------
+
+You must `create an account <https://mailsac.com/register>`_ to reply to emails. You'll get a few to start out, then can buy more as needed.
+

about/intro_curl.bash

@@ -0,0 +1,51 @@
+$ curl -s -X GET https://mailsac.com/api/addresses/user1%40mailsac.com/messages | jq ".[0]"
+
+{
+  "_id": "BotvTxaona7gLID1Adtpfj8Fnfi7HSSv-0",
+  "from": [
+    {
+      "address": "microsoftstore@e.microsoft.com",
+      "name": "Microsoft Store"
+    }
+  ],
+  "to": [
+    {
+      "address": "user1@mailsac.com",
+      "name": ""
+    }
+  ],
+  "cc": null,
+  "bcc": null,
+  "subject": "Ahoy, Sea of Thieves for PC is here",
+  "savedBy": null,
+  "originalInbox": "user1@mailsac.com",
+  "inbox": "user1@mailsac.com",
+  "domain": "mailsac.com",
+  "received": "2018-03-29T18:28:07.732Z",
+  "size": 23420,
+  "attachments": null,
+  "ip": "65.55.234.211",
+  "via": "144.202.71.79",
+  "folder": "inbox",
+  "labels": [],
+  "read": null,
+  "rtls": true,
+  "links": [
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.C.K0.-.CMHlNS",
+    "http://msstorepromoemail.blob.core.windows.net/windows-store-edits/Nav_MSFT_Logo.jpg",
+    "http://msstorepromoemail.blob.core.windows.net/windows-store-edits/Nav_WhiteSpace330.jpg",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.D.K0.-.CRfmrT",
+    "https://msstorepromoemail.blob.core.windows.net/15198-ws-final-fantasy-sea-of-thieves-ga-en-us/15198_WS_Sea_of_Thieves_GA_HCL_01.jpg",
+    "https://msstorepromoemail.blob.core.windows.net/15198-ws-final-fantasy-sea-of-thieves-ga-en-us/15198_WS_Sea_of_Thieves_GA_HCL_02.jpg",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.F.K0.-.C1qsMW",
+    "https://msstorepromoemail.blob.core.windows.net/15198-ws-final-fantasy-sea-of-thieves-ga-en-us/15198_WS_Sea_of_Thieves_GA_HCL_03.jpg",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.G.K0.-.C60tqX",
+    "https://support.xbox.com/games/game-setup/cross-play.",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.H.K0.-.CcBw4Y",
+    "https://support.xbox.com/games/game-titles/xbox-play-anywhere-help.",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.J.K0.-.CpMBp0",
+    "href=https://account.microsoft.com/profile/unsubscribe?CTID=0&ECID=jIce0uXtDC5qRlyCYqZsz5yCLndUMgkkElK5ftB2%2B2E%3D&K=5fdd51f6-8b3e-4bec-9878-4edd2310dfda&CMID=419741&D=636579325644736709&PID=18000&TID=00000000-0000-0000-0000-000000000001",
+    "href=https://e.microsoft.com/Key-3567701.C.CQZpy.K.K0.-.CtkD31"
+  ],
+  "spam": 1.3370381090039505e-09
+}

about/introduction.rst

@@ -0,0 +1,31 @@
+.. _about_intro: 
+
+Introduction
+============
+
+With Mailsac, it's super easy to interact with email via REST API, webhooks and websockets. You can
+reserve and release email addresses, check messages, download attachments, and route mail.
+
+.. tip:: All API endpoints can be found in the `API Documentation <https://mailsac.com/docs/api/>`_
+
+--------------------------------------------
+
+------------
+Curl Example
+------------
+
+You can use curl to view emails sent to user1@mailsac.com
+
+.. literalinclude:: intro_curl.bash
+    :language: bash
+    :lines: 1
+
+Information about the most recent email is returned as JSON
+
+.. literalinclude:: intro_curl.bash
+    :language: bash
+    :emphasize-lines: 1
+    :lines: 2-35,49-51
+.. tip:: This may look for more information than you need. But it provides
+         a great example of all the hard work mailsac has done to make parsing
+         of email easier.