Merge pull request #30 from mailsac/services_private_addresses

Services private addresses

index.rst

@@ -55,6 +55,7 @@ Table of Contents
    services/mailredirect
    services/slack_webhook/slack_webhook
    services/private_domains/private_domains
+   services/private_addresses/private_addresses
    services/email_validation/email_validation
 
 

services/forwarding/forwarding.rst

@@ -12,6 +12,8 @@ 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_forward_to_another_mailsac_address:
+
 Forward to Another Mailsac Address
 ----------------------------------
 
@@ -45,8 +47,8 @@ A Catch-All email address can be configured by selecting `Manage Domains`_ from
 the Dashboard_, then choosing *Manage* next to the domain, and then selecting
 the *Forwarding* tab.
 
-Slack Email Forwarding
-----------------------
+Forward to Slack
+----------------
 
 Emails sent to a private address or Catch-All can be forwarded
 :ref:`to a Slack Channel <doc_slack_webhook>`.
@@ -60,7 +62,9 @@ from the Dashboard_. Select the *Settings* button next to the email address to
 manage, then input the Slack Webhook URL and select *Save Settings*.
 Step-by-Step instructions are :ref:`provided <doc_slack_webhook>`.
 
-Webhook Forwarding
+.. _sec_webhook_forwarding:
+
+Forward to Webhook
 ------------------
 
 Private addresses and Catch-All addresses can have their mail forwarded to a

services/private_addresses/curl_reserve_private_address.txt

@@ -0,0 +1,17 @@
+curl -X POST -H "Mailsac-Key: YOUR_API_KEY_HERE" https://mailsac.com/api/addresses/unitedmonkey@mailsac.com
+
+# Output from curl
+{
+    "_id": "unitedmonkey@mailsac.com",
+    "catchAll": null,
+    "created": "2020-07-23T14:49:10.129Z",
+    "enablews": null,
+    "forward": null,
+    "info": "",
+    "owner": "monkeyman",
+    "password": null,
+    "updated": "2020-07-23T14:49:10.129Z",
+    "webhook": null,
+    "webhookSlack": null,
+    "webhookSlackToFrom": null
+}

services/private_addresses/nodejs_reserve_private_address.js

@@ -0,0 +1,27 @@
+const superagent = require('superagent')
+
+superagent
+  .post('https://mailsac.com/api/addresses/unitedmonkey@mailsac.com')
+  .set('Mailsac-Key', 'YOUR_API_KEY_HERE')
+  .then((reservation) => {
+      console.log(reservation.body)
+  })
+  .catch(err => {
+      console.log(err.message)
+  })
+/*
+{
+  _id: 'unitedmonkey@mailsac.com',
+  owner: 'monkeyman',
+  forward: null,
+  enablews: null,
+  webhook: null,
+  webhookSlack: null,
+  webhookSlackToFrom: null,
+  catchAll: null,
+  password: null,
+  info: '',
+  created: '2020-07-23T15:00:00.935Z',
+  updated: '2020-07-23T15:00:00.935Z'
+}
+*/

services/private_addresses/private_addresses.rst

@@ -0,0 +1,31 @@
+.. _doc_private_addresses:
+
+.. _sec_private_addresses:
+
+Private Email Addresses
+=======================
+
+Messages sent to a Private Email Address are only visible by the owner of
+the Private Email Address.
+
+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>`
+- `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/>`_
+
+Reserve a Private Address
+-------------------------
+
+.. include:: ./reserve_private_address.rst
+
+Private Addresses In a Custom Domain
+------------------------------------
+
+Private Addresses can be used in :ref:`Custom Domains <doc_privatedomains>`.
+This allows an address within a :ref:`Custom Domain <doc_privatedomains>` to
+have the features of a 
+:ref:`Private Email Address <sec_private_addresses>`.

services/private_addresses/python_reserve_private_address.py

@@ -0,0 +1,22 @@
+import requests
+from pprint import pprint
+
+headers = {'Mailsac-Key': 'YOUR_API_KEY_HERE'}
+url = 'https://mailsac.com/api/addresses/unitedmonkey@mailsac.com'
+
+r = requests.post(url, headers=headers)
+pprint(r.json())
+'''
+{'_id': 'unitedmonkey@mailsac.com',
+ 'catchAll': None,
+ 'created': '2020-07-23T15:04:15.981Z',
+ 'enablews': None,
+ 'forward': None,
+ 'info': '',
+ 'owner': 'mjmayer',
+ 'password': None,
+ 'updated': '2020-07-23T15:04:15.981Z',
+ 'webhook': None,
+ 'webhookSlack': None,
+ 'webhookSlackToFrom': None}
+ '''

services/private_addresses/reserve_private_address.rst

@@ -0,0 +1,26 @@
+.. _doc_reserve_private_address:
+
+.. tabs::
+   .. tab:: Mailsac Website
+
+      .. figure:: reserve_private_address.gif
+
+         Reserve private address
+
+   .. tab:: curl
+
+       .. literalinclude:: curl_reserve_private_address.txt
+          :language: bash
+          :caption: Reserve Private Address
+
+   .. tab:: Node.js Javascript 
+
+       .. literalinclude:: nodejs_reserve_private_address.js
+          :language: javascript
+          :caption: Reserve Private Address
+
+   .. tab:: Python
+
+       .. literalinclude:: python_reserve_private_address.py
+          :language: python
+          :caption: Reserve Private Address