Merge pull request #18 from mailsac/get-started

Show intro + Get Started earlier, modernize FAQ

about/faq.rst

@@ -1,16 +1,22 @@
 .. _faq:
 
-FAQ
-===
+Frequently Asked Questions
+==========================
 
 Where are my email attachments?
 -------------------------------
 
-You must `download the message or parse it yourself <https://community.mailsac.com/docs/email-attachments/>`_.
+For `private addresses, the Inbox App will allow you to download attachments <https://mailsac.com/app>`_. You can also `fetch private messages with POP3 <https://mailsac.com/docs/fetch-messages-with-pop3>`_ in your email client, such as Apple Mail or GMail.
+
+Disposable emails under public email addresses disallow downloading attachments - :ref:`you must download the entire message file, or fetch attachments programmatically using the API <doc_attachments>`.
+
+For private addresses, using the `Unified Inbox App <https://mailsac.com/app>`, attachment files are downloadable.
+
+Attachments cannot be hosted publicly for download because attachments often contain viruses and spam.
 
 Why would I use Mailsac?
 ------------------------
-Any time you need a temporary email address, just make one up@mailsac.com.
+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.
 
@@ -20,7 +26,7 @@ Other uses:
 * 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
+* send mail to Mailsac for QA 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
@@ -31,41 +37,49 @@ Other uses:
 Why weren't my messages received?
 ---------------------------------
 
-There are many reasons messages may not be received by Mailsac. The
-:ref:`doc_missingmail` document in our help section provides detailed
-explanations of why messages are not received.
+There are many reasons messages may not be received or displayed by Mailsac.
+
+The :ref:`doc_missingmail` page provides detailed explanations about why messages are not received.
+
+Most often, the following happens:
 
 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
+3. Fast recycling. Without enough message storage, your inbound emails may be deleted quickly.
+4. 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>`_.
+   lift it on your `Custom Domain <https://mailsac.com/domains>`_.
+
+The Mailsac Team is highly responsive to `forum <https://forum.mailsac.com>`_ and support emails.
+Contact us and we will resolve your issue.
 
-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.
+.. tip::
+  https://forum.mailsac.com
 
+  support@team.mailsac.com
 
 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.
+If you expect to send more than a few messages per minute, you might get throttled.
 
 
 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.
+*Message storage* prevents emails from being recycled.
+
+1. If you star a message, it will not be recycled until you unstar it.
+2. Private addresses will not be recycled, up to your storage limit.
+3. Messages on custom domains will not be recycled, up to your storage limit.
 
 Can other people see messages that I starred?
 ---------------------------------------------
@@ -77,3 +91,5 @@ 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.
 
+Or, you can use `POP3 <https://mailsac.com/docs/fetch-messages-with-pop3>`_ to download
+messages on a private address or custom domain.

about/intro_curl.bash

@@ -18,34 +18,22 @@ $ curl -s -X GET https://mailsac.com/api/addresses/user1%40mailsac.com/messages
   "bcc": null,
   "subject": "Ahoy, Sea of Thieves for PC is here",
   "savedBy": null,
-  "originalInbox": "user1@mailsac.com",
+  "originalInbox": "inbox-c942bfeeafb96c0e5ce8b4e5c0d747c608@mailsac.com",
   "inbox": "user1@mailsac.com",
   "domain": "mailsac.com",
   "received": "2018-03-29T18:28:07.732Z",
   "size": 23420,
-  "attachments": null,
+  "attachments": ["c830ee26e0a326e0a30c585494793479"],
   "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"
+    "https://support.xbox.com/games/game-titles/xbox-play-anywhere-help",
+    "https://e.microsoft.com/Key-3567701.C.CQZpy.J.K0.-.CpMBp0",
+    "https://account.microsoft.com/profile/unsubscribe?CTID=0&ECID=jIce0uXtDC5qRlyCYqZsz5yCL"
   ],
-  "spam": 1.3370381090039505e-09
+  "spam": 0.331
 }

about/introduction.rst

@@ -1,12 +1,12 @@
-.. _about_intro: 
+.. _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/>`_
+.. tip:: All API endpoints can be found in the `API Specification <https://mailsac.com/docs/api/>`_
 
 --------------------------------------------
 
@@ -25,7 +25,7 @@ Information about the most recent email is returned as JSON
 .. literalinclude:: intro_curl.bash
     :language: bash
     :emphasize-lines: 1
-    :lines: 2-35,49-51
+    :lines: 2-
 .. 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.

getting_started/checkmail.rst

@@ -4,32 +4,32 @@ Check Mail
 =============
 
 Now that curl and jq are installed, we can start interacting with Mailsac API. The
-`Mailsac API Reference <https://mailsac.com/docs/api/>`_ includes all supported
-endpoints. The API Reference is great starting place, if you a familiar with
+`Mailsac API Specification <https://mailsac.com/docs/api/>`_ includes all supported
+endpoints. The API Specification reference is great starting place, if you a familiar with
 REST APIs, or for reference after completing this step-by-step introduction.
 
 In this example, we are going to check an arbitrary email address
 for mail, read that email and respond to the email.
 
 We will list inbox email messages for `user1@mailsac.com`.
-To list the available messages we will use the 
+To list the available messages we will use the
 `List Inbox Email Messages endpoint <https://mailsac.com/docs/api/#list-inbox-email-messages>`_.
 
 .. tip:: API documentation is generalized. Modifications are needed to translate an API endpoint
-   into a usable URL. The base URI of all Mailsac API requests will be https://mailsac.com. 
+   into a usable URL. The base URI of all Mailsac API requests will be https://mailsac.com.
 
-This endpoint can be accessed with :code:`GET /api/addresses/:email/messages`. You 
+This endpoint can be accessed with :code:`GET /api/addresses/:email/messages`. You
 will substitute `:email` with `user1@mailsac.com` giving us :code:`GET /api/addresses/user1@mailsac.com/messages`.
-Curl does not encode URLs. The `@` character needs to be URL encoded as `%40`. 
-:code:`GET /api/addresses/user1%40mailsac.com/messages`. The base URI of the Mailsac API is Mailsac.com, which 
+Curl does not encode URLs. The `@` character needs to be URL encoded as `%40`.
+:code:`GET /api/addresses/user1%40mailsac.com/messages`. The base URI of the Mailsac API is Mailsac.com, which
 translates to :code:`https://mailsac.com/api/addresses/user1%40mailsac.com/messages`
 
 .. tip:: You can validate the url is properly formatted by accessing it in your web browser. Go ahead and try it with
    our `example <https://mailsac.com/api/addresses/user1%40mailsac.com/messages>`_ or try it with a different email address.
 
 Curl requires us to add a few extra parameters. `-X GET` instructs curl to us a HTTP GET request. `-s` suppresses
 a progress bar. In the command below we pipe the contents of curl into JQ for JSON formatting. JQ requires a filter to function.
-We are using the simplest filter `"."` which matches all JSON. `user1@mailsac` is a popular address and receives lots of email. 
+We are using the simplest filter `"."` which matches all JSON. `user1@mailsac` is a popular address and receives lots of email.
 JQ will only show the first JSON object with the filter `".[0]"`
 
 .. literalinclude:: /about/intro_curl.bash
@@ -41,7 +41,7 @@ JQ will only show the first JSON object with the filter `".[0]"`
 .. literalinclude:: /about/intro_curl.bash
     :language: bash
     :caption: **Inbox message**
-    :lines: 2-35,49-51
+    :lines: 2-
 
 As you can see, the JSON contains information about the email message including  to address,
 from address, subject, time stamp, attachments and much more. Make note of the `_id` field, you