Merge pull request #43 from mailsac/update_mail_storage

Add email deletion examples to message storage

index.rst

@@ -46,7 +46,7 @@ Table of Contents
    :name: sec-services
 
    services/introduction
-   services/mailstorage
+   services/message_storage/message_storage
    services/attachments
    services/email_hosting
    services/webhook

services/email_capture/email_capture.rst

@@ -96,7 +96,7 @@ Emails sent via :code:`capture.mailsac.com` can be automatically
 :ref:`starred <sec_starred_messages>`, which keeps the email private, by
 enabling the Make Capture Email Private option under `Account Settings
 <https://mailsac.com/account>`_. Starred messages count towards
-:ref:`doc_mailstorage` limits.
+:ref:`doc_message_storage` limits.
 
 .. figure:: private_captured_email_option.png
 

services/introduction.rst

@@ -7,7 +7,7 @@ To get the most out of Mailsac, an account and API key are required. Getting a p
 entitle you to support. Once you are signed up with Mailsac you can start exploring
 the services provided:
 
-* :ref:`Message  Storage <doc_mailstorage>`
+* :ref:`Message  Storage <doc_message_storage>`
 * :ref:`Email Attachments <doc_attachments>`
 * :ref:`Email Hosting <doc_emailhosting>`
 * :ref:`Receive Email via JSON Webhook <doc_webhook_setup>`

services/message_storage/delete_message.js

@@ -0,0 +1,21 @@
+const superagent = require('superagent')
+const mailsac_api_key = 'YOUR_API_KEY_HERE'
+const messageId = 'YOUR_MESSAGE_ID'
+
+superagent
+  .delete('https://mailsac.com/api/addresses/bclinton@mailsac.com/messages/' + messageId)
+  .set('Mailsac-Key', mailsac_api_key)
+  .then((data) => {
+      console.log(data.body)
+  })
+  .catch(err => {
+      console.error(err.message);
+  })
+
+/*
+{
+    message: 'Message was deleted.',
+    _id: 'sepjrPlPJsJEm6F8_cHeuCAcs-0',
+    inbox: 'bclinton@mailsac.com'
+}
+*/

services/message_storage/delete_message.py

@@ -0,0 +1,14 @@
+import requests
+from pprint import pprint
+
+message_id = 'YOUR_MESSAGE_ID'
+headers = {'Mailsac-Key': 'YOUR_API_KEY_HERE'}
+url = 'https://mailsac.com/api/addresses/bclinton@mailsac.com/messages/' + message_id
+r = requests.delete(url, headers=headers)
+pprint(r.json())
+
+'''
+{'_id': '4xnxBtJpZxLQTU2MvcIPD65cdWQC-0',
+ 'inbox': 'bclinton@mailsac.com',
+ 'message': 'Message was deleted.'}
+'''

services/message_storage/delete_message.sh

@@ -0,0 +1,4 @@
+curl -s -H "Mailsac-Key: YOUR_API_KEY_HERE" \
+    -X DELETE https://mailsac.com/api/addresses/bclinton@mailsac.com/messages/fkwhpdnzsQ81MdllcqfqCd3jQq-0 
+# curl output
+{"message":"Message was deleted.","_id":"fkwhpdnzsQ81MdllcqfqCd3jQq-0","inbox":"bclinton@mailsac.com"}

services/message_storage/message_storage.rst

@@ -0,0 +1,163 @@
+.. role:: red
+.. _`Mailsac Website`: https://mailsac.com
+.. _`messageId`: https://mailsac.com/docs/api/#example-email-message-object
+.. _`List Inbox Email Messages Endpoint`: https://mailsac.com/docs/api/#list-inbox-email-messages
+.. _`WebSocket Frame`: https://mailsac.com/docs/api/#example-web-socket-frame
+.. _`Webhook`: https://mailsac.com/docs/api/#webhooks
+.. _`Unified Inbox`: https://mailsac.com/app
+.. _Dashboard: https://mailsac.com/dashboard
+.. _`Custom Domains`: https://mailsac.com/domains
+
+.. _doc_message_storage:
+
+Message Storage
+===============
+
+Message storage defines how many messages can be stored before mail before
+messages are recycled. Messages that are sent to a :ref:`Custom Domain
+<doc_custom_domains>`, :ref:`doc_private_addresses`, or `starred messages`_
+count towards message storage.
+
+.. _sec_message_recycling:
+
+When are Messages Recycled?
+---------------------------
+
+Messages sent to non-private addresses and domains will be recycled at times
+to ensure capacity for new messages.
+
+Messages sent to :ref:`private domains <doc_custom_domains>`, private addresses,
+and `starred messages`_ associated with Mailsac are recycled once the storage 
+limit is reached.
+
+Examples
+--------
+
+1. If your storage limit is 100 messages and you have starred 125 messages, the
+   oldest 25 messages will be recycled.
+2. If your storage limit is 100 messages and you have 75 messages in your
+   private domain. No messages will be recycled.
+3. If your storage limit is 100 messages and you have 150 messages in your
+   private domain, the oldest 50 messages will be recycled.
+4. If your storage limit is 100 messages and you have 50 messages in 3
+   private inboxes (total 150 messages), the oldest 50 messages will be
+   recycled.
+
+
+Getting More Storage
+--------------------
+Message storage can be purchased on a per-message basis in blocks listed on the 
+`pricing page <https://mailsac.com/pricing>`_.
+
+.. _sec_starred_messages:
+
+Starred Messages
+----------------
+When you star a message, it counts towards your overall storage. 
+
+:red:`Use the star symbol ★`
+
+Your user Dashboard_ has links to all 
+inboxes where you starred messages.
+
+You can star messages on any address, including those you own or other 
+public addresses.
+
+Managing Storage
+----------------
+
+Most customers will never need to manage message storage, since emails are
+:ref:`automatically recycled <sec_message_recycling>`.
+
+Messages can proactively be deleted:
+
+- Per message
+- Per private inbox
+- Per private domain
+
+.. _sec_delete_a_message:
+
+Delete a Message
+-------------------
+
+REST API examples require :code:`messageId` parameter. messageId_ can be found
+using the `List Inbox Email Messages Endpoint`_, a `WebSocket Frame`_, and
+`Webhook POST <Webhook_>`_.
+
+
+.. tabs::
+   .. tab:: Mailsac Website
+
+      .. figure:: delete_message_website.gif
+
+         Delete message using the `Mailsac Website`_
+
+   .. tab:: Unified Inbox
+
+      .. figure:: delete_message_unified_inbox.gif
+
+         Delete using the `Unified Inbox`_ (requires
+         :ref:`Private Address <doc_private_addresses>`)
+
+   .. tab:: curl
+
+       .. literalinclude:: delete_message.sh
+          :language: bash
+          :caption: Delete using curl (requires messageId_)
+
+   .. tab:: Node.js Javascript 
+
+       .. literalinclude:: delete_message.js
+          :language: javascript
+          :caption: Delete message using Node.js. requires
+                    :code:`npm install superagent`
+
+   .. tab:: Python
+
+       .. literalinclude:: delete_message.py
+          :language: python
+          :caption: Read message using Python
+
+Purge Inbox
+-----------
+
+Examples require the Inbox to be a :ref:`Private Address
+<doc_private_addresses>`
+
+.. tabs::
+   .. tab:: Mailsac Website
+
+      .. figure:: purge_inbox_website.gif
+
+         Purge inbox using the `Mailsac Website`_
+
+   .. tab:: curl
+
+       .. literalinclude:: purge_inbox.sh
+          :language: bash
+          :caption: Purge inbox using curl (requires messageId_)
+
+   .. tab:: Node.js Javascript 
+
+       .. literalinclude:: purge_inbox.js
+          :language: javascript
+          :caption: Purge inbox using Node.js. requires
+                    :code:`npm install superagent`
+
+   .. tab:: Python
+
+       .. literalinclude:: purge_inbox.py
+          :language: python
+          :caption: Purge inbox using Python
+
+Purge Domain
+------------
+
+All messages in a verified domain can be deleted.
+
+From the Dashboard_, select `Custom Domains`_, select manage next to the domain,
+click on the advanced tab, and click on the button "Irreversibly Delete Emails".
+
+.. figure:: purge_domain_website.png
+   :width: 400px
+   :align: center

services/message_storage/purge_inbox.js

@@ -0,0 +1,16 @@
+const superagent = require('superagent')
+const mailsac_api_key = 'YOUR_API_KEY_HERE'
+
+superagent
+  .delete('https://mailsac.com/api/addresses/bclinton@mailsac.com/messages/')
+  .set('Mailsac-Key', mailsac_api_key)
+  .then((res) => {
+      console.log(res.status)
+  })
+  .catch(err => {
+      console.error(err.message);
+  })
+
+/*
+204
+*/

services/message_storage/purge_inbox.py

@@ -0,0 +1,10 @@
+import requests
+
+headers = {'Mailsac-Key': 'YOUR_API_KEY_HERE'}
+url = 'https://mailsac.com/api/addresses/bclinton@mailsac.com/messages/'
+r = requests.delete(url, headers=headers)
+print(r.status_code)
+
+'''
+204
+'''

services/message_storage/purge_inbox.sh

@@ -0,0 +1,4 @@
+curl -s -H "Mailsac-Key: YOUR_API_KEY_HERE" \
+    -X DELETE https://mailsac.com/api/addresses/bclinton@mailsac.com/messages
+
+# Return Code 204 No Content

services/private_addresses/private_addresses.rst

@@ -1,7 +1,5 @@
 .. _doc_private_addresses:
 
-.. _sec_private_addresses:
-
 Private Email Addresses
 =======================
 
@@ -28,4 +26,4 @@ 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 
-:ref:`Private Email Address <sec_private_addresses>`.
+:ref:`Private Email Address <doc_private_addresses>`.