Merge pull request #47 from mailsac/collective_review_of_docs

Collective review of docs

about/faq.rst

@@ -1,3 +1,6 @@
+.. _`REST API`: https://mailsac.com/api
+.. _`Unified Inbox`: https://mailsac.com/app
+
 .. _faq:
 
 Frequently Asked Questions
@@ -6,20 +9,15 @@ Frequently Asked Questions
 Where are my 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>`.
+Email attachments are not viewable for public addresses from the Website.
+Attachments must be downloaded using `REST API`_.
 
-For private addresses, when using the `Unified Inbox App
-<https://mailsac.com/app>`_, attachment files are downloadable.
+Attachments on emails sent to :ref:`Private Addresses <doc_private_addresses>`
+can be viewed in the `Unified Inbox`_ or in an email client using
+:ref:`POP3 <sec_reading_mail_pop3>`.
 
-Attachments cannot be hosted publicly for download because attachments often
-contain viruses and spam.
+:ref:`Read more about email attachments at Mailsac
+<sec_reading_mail_attachments>`.
 
 Why would I use Mailsac?
 ------------------------

api_examples/getting_started/getting_started.rst

@@ -20,6 +20,14 @@ This example will show how to do the following using the REST API.
 If you are familiar with REST APIs the `REST API Specification`_ can be
 referenced during this example.
 
+REST API Overview
+-----------------
+
+REST API interaction is at the core of Mailsac. The examples in this section
+will provide you with easy to understand curl examples. For additional code
+examples (Nodejs and Python) see: :ref:`Reading Email <doc_reading_mail>`
+and :ref:`Sending Mail <doc_sending_mail>`.
+
 Prerequisites
 -------------
 

api_examples/index.rst

@@ -2,7 +2,6 @@
    :maxdepth: 1
    :name: toc-api-examples
 
-   overview
    getting_started/getting_started
    delivery_confirmation
    download_all_inbox_attachments

help/account_management/account_management.rst

@@ -27,7 +27,8 @@ An account password can be changed on the Website under
 `Password Reset Form <https://mailsac.com/password-reset>`_ to send a password
 reset email.
 
-.. _sec_account_deletion:
+
+.. _sec_api_key_management:
 
 API Key Management
 ------------------
@@ -102,6 +103,8 @@ Dashboard_.
 
    Monthly outbound message count
 
+.. _sec_account_deletion:
+
 Account Deletion
 ----------------
 

help/missing_mail.rst

@@ -2,8 +2,8 @@
 
 .. _doc_missingmail:
 
-Missing Mail
-============
+Missing Email
+=============
 
 If you have sent email to a *@mailsac.com* address or a private domain hosted
 at Mailsac and it was not received, this document will help you find out why.
@@ -67,13 +67,13 @@ email that can be sent.
 
 GMail
 ^^^^^
-GMail is not designed for sending bulk mail. The service places `limits 
+GMail is not designed for sending bulk mail. The service places `limits
 <https://support.google.com/mail/answer/22839?hl=en>`_ on the number of
 emails sent per day and the number of recipients.
 
 SendGrid
 ^^^^^^^^
-Messages sent through SendGrid are often queued and may not be sent 
+Messages sent through SendGrid are often queued and may not be sent
 immediately.
 
 Mandrill
@@ -85,7 +85,7 @@ Request Whitelist
 -----------------
 
 Whitelisting is only necessary if mail delivery is being slowed due to Mailsac
-throttling. A whitelist request can be submitted using the `IP Whitelist Form 
+throttling. A whitelist request can be submitted using the `IP Whitelist Form
 <https://mailsac.com/whitelist-request>`_ from the Dashboard_.
 
 Whitelisting can be requested for:

index.rst

@@ -34,22 +34,14 @@ Table of Contents
 
 .. toctree::
    :maxdepth: 1
-   :caption: WebSocket and Webhook Examples
-   :name: sec-websocket-examples:
-
-   websocket_examples/index
-
-
-.. toctree::
-   :maxdepth: 1
-   :caption: How Mailsac Works
+   :caption: Use and Integration of Mailsac
    :name: sec-services
 
-   services/introduction
    services/message_storage/message_storage
    services/attachments
    services/email_hosting
-   services/webhook
+   services/webhook/webhook
+   services/websocket/websocket
    services/forwarding/forwarding
    services/sending_mail/sending_mail
    services/reading_mail/reading_mail

services/attachments.rst

@@ -15,7 +15,14 @@ There are several ways to download attachments when authenticated to the Mailsac
 3. Attachments can be downloaded using the MD5 hash of the attachment, `using the common-attachments API <https://mailsac.com/docs/api/#download-a-common-attachment>`_.
 4. Attachments can be parsed out of the `raw` message using the `API <https://mailsac.com/docs/api/#example-email-message-object>`_.
 
+Additional information on reading mail, including code examples, can be found
+in :ref:`Reading Email <doc_reading_mail>`.
+
 Sending Attachments
 --------------------
 
-Attachments on outgoing messages are only supported `through the API <https://mailsac.com/docs/api/#send-email-messages>`_.
+Attachments on outgoing messages are only supported
+`through the API <https://mailsac.com/docs/api/#send-email-messages>`_.
+
+Additional information on sending mail, including code examples, can be found
+in :ref:`Sending Email <doc_sending_mail>`.

services/email_capture/email_capture.rst

@@ -75,7 +75,7 @@ are provided.
           :language: bash
           :caption: Validate email was received
 
-   .. tab:: Node.js Javascript 
+   .. tab:: Node.js Javascript
 
        .. literalinclude:: javascript_validation.js
           :language: javascript
@@ -126,8 +126,8 @@ Email Capture Flow
 -------------------
 
 In the Email Capture model the Mail User Agent uses Mailsac's receiving Mail
-Transfer Agent as the outbound MTA. The Mailsac MTA will accept all mail,
-regardless of the destination domain.
+Transfer Agent as the outbound MTA (relay). The Email Capture MTA will
+accept all mail, regardless of the destination domain.
 
 Considerations
 --------------

services/forwarding/forwarding.rst

@@ -4,14 +4,16 @@
 
 .. _doc_forwarding:
 
-Email Forwarding
-================
+Email Forwarding Overview
+=========================
 
-Forwarding allows email to be sent on to a further email address or
-service (Webhook, WebSocket, Slack Webhook). Private addresses and custom
+Forwarding, or routing, allows email to be sent on to a further email address
+or service (Webhook, WebSocket, Slack Webhook). Private addresses and custom
 domains can be configured for email forwarding. Forwarding is not available on
 disposable email addresss.
 
+.. _sec_forwarding_catchall:
+
 Catch-All Domain Forwarding Addresses
 -------------------------------------
 
@@ -41,7 +43,7 @@ Catch-All addresses can be forwarded to:
 - :ref:`WebSocket <sec_websocket_forwarding>`
 
 From the Dashboard_, select `Manage Email Addresses`, then select settings
-icon next to the Catch-All address. 
+icon next to the Catch-All address.
 
 .. figure:: catch-all_forwarding_settings.png
     :align: center
@@ -132,7 +134,7 @@ to the email address to manage, then check the box labeled *Enable forwarding
 all incoming email via web socket*, and select *Save Settings*.
 
 A code example for a WebSocket is available :ref:`available
-<doc_websocket_example_overview>`.
+<doc_websocket>`.
 
 Additional information about the WebSocket endpoint, authentication and example
 frame format is show in the `API Documentation

services/private_addresses/private_addresses.rst

@@ -11,7 +11,7 @@ Private Email Addresses have additional features:
 - :ref:`sec_forward_to_another_mailsac_address`
 - :ref:`Forward to Slack <doc_slack_webhook>`
 - :ref:`sec_webhook_forwarding`
-- :ref:`Forward to a Web Socket <doc_websocket_example_overview>`
+- :ref:`Forward to a Web Socket <doc_websocket>`
 - `Read / Send Mail using a mail client <https://mailsac.com/docs/fetch-messages-with-pop3>`_
 - `Purge inbox <https://blog.mailsac.com/2020/07/21/easy-purging-of-inboxes/>`_
 
@@ -25,5 +25,5 @@ Private Addresses In a Custom Domain
 
 Private Addresses can be used in :ref:`Custom Domains <doc_custom_domains>`.
 This allows an address within a :ref:`Custom Domain <doc_custom_domains>` to
-have the features of a 
+have the features of a
 :ref:`Private Email Address <doc_private_addresses>`.

services/reading_mail/reading_mail.rst

@@ -6,8 +6,8 @@
 
 .. _doc_reading_mail:
 
-Reading Mail
-============
+Reading Email
+=============
 
 There are several ways for to view email messages using Mailsac
 
@@ -18,8 +18,8 @@ There are several ways for to view email messages using Mailsac
 
 .. _sec_read_mail_message:
 
-Read a Mail Message
--------------------
+Read an Email Message
+---------------------
 
 .. tabs::
    .. tab:: Mailsac Website
@@ -41,7 +41,7 @@ Read a Mail Message
           :caption: Read using curl. Requires
                     `JQ <https://stedolan.github.io/jq/>`_
 
-   .. tab:: Node.js Javascript 
+   .. tab:: Node.js Javascript
 
        .. literalinclude:: reading_mail.js
           :language: javascript
@@ -83,7 +83,7 @@ The `Unified Inbox`_ provides a way to view the mail of all
 
 .. figure:: unified_inbox_view.png
 
-The `Unified Inbox`_ is useful for managing multiple email addresses. 
+The `Unified Inbox`_ is useful for managing multiple email addresses.
 
 .. _sec_reading_mail_rest_api:
 
@@ -140,3 +140,20 @@ etc) using these POP3 settings:
 
 To configure a mail client for sending see the :ref:`Sending Mail via SMTP
 Section <sec_sendingmail_smtp>`.
+
+.. _sec_reading_mail_attachments:
+
+Viewing Email Attachments
+-------------------------
+
+For :ref:`private addresses <doc_private_addresses>`, the `Unified Inbox`_
+allows downloading of attachments. Email fetched from private addresses using
+:ref:`POP3 from an email client <sec_reading_mail_pop3>`
+such as Apple Mail or GMail, will include attachments.
+
+Public email addresses disallow downloading attachments
+- :ref:`you must download the entire message file, or fetch attachments
+programmatically using the API <doc_attachments>`.
+
+Attachments cannot be hosted publicly for download because attachments often
+contain viruses and spam.

services/sending_mail/sending_mail.rst

@@ -3,12 +3,12 @@
 .. _Web Form: https://mailsac.com/compose
 .. _API Key: https://mailsac.com/api-keys
 
-.. _doc_sendingmail:
+.. _doc_sending_mail:
 
-Sending Mail
-============
+Sending Email
+=============
 
-Mail can be sent via the following methods:
+Email can be sent via the following methods:
 
 - `Web Form`_
 - `Unified Inbox`_
@@ -17,13 +17,13 @@ Mail can be sent via the following methods:
 
 .. _sec_send_mail_message:
 
-Send a Mail Message
--------------------
+Send an Email Message
+---------------------
 
 .. tabs::
    .. tab:: Mailsac Website
 
-      .. figure:: webform.png 
+      .. figure:: webform.png
 
          Send using the `Compose Message Form <Web Form_>`_
 
@@ -39,7 +39,7 @@ Send a Mail Message
           :language: bash
           :caption: Send using curl
 
-   .. tab:: Node.js Javascript 
+   .. tab:: Node.js Javascript
 
        .. literalinclude:: sending_mail.js
           :language: javascript
@@ -60,7 +60,7 @@ The :code:`from` address must be a :ref:`Private Address
 Sending credits
 ---------------
 
-Sending mail, both replies and new messages, is available only from private
+Sending Email, both replies and new messages, is available only from private
 addresses and private domains. Sending or replying requires `mail credits
 <https://mailsac.com/pricing>`_.
 
@@ -122,7 +122,7 @@ etc) using these SMTP settings:
 | **Encryption**        | TLS                                                   |
 +-----------------------+-------------------------------------------------------+
 
-To configure a mail client for reading see the :ref:`Reading Mail via POP3 
+To configure a mail client for reading see the :ref:`Reading Mail via POP3
 Section <sec_reading_mail_pop3>`.
 
 .. _doc_internal_smtp: