ethyca · eastandwestwind · Sep 7, 2022 · Sep 1, 2022 · Sep 1, 2022 · Sep 2, 2022
diff --git a/docs/fidesops/docs/guides/email_communications.md b/docs/fidesops/docs/guides/email_communications.md
@@ -1,12 +1,12 @@
-# Configure Email Communications
-## What is email used for?
+# Configure Automatic Emails
+## What is a fidesops Email Connection?
 
-Fidesops supports email server configurations for sending processing notices to privacy request subjects. Future updates will support outbound email communications with data processors.
+Fidesops supports configuring third party email servers to handle outbound communications.
 
 Supported modes of use:
 
-- Subject Identity Verification - for more information on identity verification in subject requests, see the [Privacy Requests](privacy_requests.md#subject-identity-verification) guide.
-- Erasure Request Email Fulfillment - sends an email to configured third parties to process erasures for a given data subject.  See [Email Connectors](email_connectors.md) for more information.
+- Subject Identity Verification - sends a verification code to the user's email address prior to  for more information on identity verification in subject requests, see the [Privacy Requests](privacy_requests.md#subject-identity-verification) guide.
+- Erasure Request Email Fulfillment - sends an email to configured third parties to process erasures for a given data subject.  See [creating Email Connectors](#create-an-email-connector) for more information.
 
 ## Prerequisites
 
@@ -16,12 +16,12 @@ Fidesops currently supports Mailgun for email integrations. Ensure you register
 
     Follow the [Mailgun documentation](https://documentation.mailgun.com/en/latest/api-intro.html#authentication-1) to create a new Domain Sending Key for fidesops. 
 
-    !!! Note 
-        Mailgun automatically generates a **primary account API key** when you sign up for an account. This key allows you to perform all CRUD operations via Mailgun's API endpoints, and for any of your sending domains. For security purposes, using a new **domain sending key** is recommended over your primary API key.
+!!! Note 
+    Mailgun automatically generates a **primary account API key** when you sign up for an account. This key allows you to perform all CRUD operations via Mailgun's API endpoints, and for any of your sending domains. For security purposes, using a new **domain sending key** is recommended over your primary API key.
 
 ## Configuration
 
-### Create the email configuration
+### Create the email config
 
 ```json title="<code>POST api/v1/email/config"
 {
@@ -47,7 +47,7 @@ Fidesops currently supports Mailgun for email integrations. Ensure you register
 
 ### Add the email configuration secrets 
 
-```json title="<code>POST api/v1/email/config/{{email_config_key}}/secret"
+```json title="<code>POST api/v1/email/config/{email_config_key}/secret"
 {
     "mailgun_api_key": "nc123849ycnpq98fnu"
 }
@@ -58,3 +58,102 @@ Fidesops currently supports Mailgun for email integrations. Ensure you register
 |---|----|
 | `mailgun_api_key` | Your Mailgun Domain Sending Key. |
 
+## Email third-party services
+
+Once your email server is configured, you can create an email connector to send automatic erasure requests to third-party services. Fidesops will gather details about each collection described in the connector, and send a single email to the service after all collections have been visited. 
+
+!!! Note
+    Fidesops does not collect confirmation that the erasure was completed by the third party.
+
+
+### Create the connector
+
+Ensure you have created your [email configuration](#configuration) prior to creating a new email connector.
+
+```json title="<code>PATCH api/v1/connection</code>"
+[
+  { 
+    "name": "Email Connection Config",
+    "key": "third_party_email_connector",
+    "connection_type": "email",
+    "access": "write"
+  }
+]
+```
+
+| Field | Description |
+|----|----|
+| `key` | A unique key used to manage your email connector. This is auto-generated from `name` if left blank. Accepted values are alphanumeric, `_`, and `.`. |
+| `name` | A unique user-friendly name for your email connector. |
+| `connection_type` | Must be `email` to create a new email connector. |
+| `access` | Email connectors must be given `write` access in order to send an email. |
+
+
+### Configure notifications
+
+Once your email connector is created, configure any outbound email addresses:
+
+```json title="<code>PUT api/v1/connection/{email_connection_config_key}/secret</code>" 
+{
+    "test_email": "[email protected]",
+    "to_email": "[email protected]
+}
+```
+
+| Field | Description |
+|----|----|
+| `{email_connection_config_key}` | The unique key that represents the email connection to use. |
+| `to_email` | The user that will be notified via email to complete an erasure request. *Only one `to_email` is supported at this time.* |
+| `test_email` | *Optional.* An email to which you have access for verifying your setup. If your email configuration is working, you will receive an email with mock data similar to the one sent to third-party services. |
+
+### Configure the dataset
+
+Lastly, configure the collections and fields you would like to request be erased or masked. Fidesops will use these fields to compose an email to the third-party service. 
+
+```json title="<code>PUT api/v1/connection/{email_connection_config_key}/dataset" 
+[
+    {
+      "fides_key": "email_dataset",
+      "name": "Dataset not accessible automatically",
+      "description": "Third party data - will email to request erasure",
+      "collections": [
+        {
+          "name": "daycare_customer",
+          "fields": [
+            {
+              "name": "id",
+              "data_categories": [
+                "system.operations"
+              ],
+              "fidesops_meta": {
+                "primary_key": true
+              }
+            },
+            {
+              "name": "child_health_concerns",
+              "data_categories": [
+                "user.biometric_health"
+              ]
+            },
+            {
+              "name": "user_email",
+              "data_categories": [
+                "user.contact.email"
+              ],
+              "fidesops_meta": {
+                "identity": "email"
+              }
+            }
+          ]
+        }
+      ]
+    }
+]
+```
+
+| Field | Description |
+|----|----|
+| `fides_key` | A unique key used to manage your email dataset. This is auto-generated from `name` if left blank. Accepted values are alphanumeric, `_`, and `.`. |
+| `name` | A unique user-friendly name for your email dataset. |
+| `description` | Any additional information used to describe this email dataset. |
+| `collections` | Any collections and associated fields belonging to the third party service, similar to a configured fidesops [Dataset](datasets.md). If you do not know the exact data structure of a third party's database, you can configure a single collection with the fields you would like masked. **Note:** A primary key must be specified on each collection. |
diff --git a/docs/fidesops/docs/guides/email_connectors.md b/docs/fidesops/docs/guides/email_connectors.md
diff --git a/docs/fidesops/docs/guides/privacy_requests.md b/docs/fidesops/docs/guides/privacy_requests.md
@@ -43,13 +43,13 @@ A full list of attributes available to set on the Privacy Request can be found i
 ## Subject Identity Verification 
 
 To have users verify their identity before their Privacy Request is executed, set the `subject_identity_verification_required` 
-variable in your `fidesops.toml` to `TRUE`. You must also set up an EmailConfig that lets Fidesops send automated emails 
+variable in your `fidesops.toml` to `TRUE`. You must also set up an [EmailConfig](./email_communications.md) that lets fidesops send automated emails 
 to your users.
 
-When a user submits a PrivacyRequest, they will be emailed a six-digit code.  They must supply that verification code to Fidesops
+When a user submits a PrivacyRequest, they will be emailed a six-digit code.  They must supply that verification code to fidesops
 to continue privacy request execution.  Until the Privacy Request identity is verified, it will have a status of: `identity_unverified`.
 
-```json title="<code>POST api/v1/privacy-request/<privacy_request_id>/verify</code>"
+```json title="<code>POST api/v1/privacy-request/{privacy_request_id}/verify</code>"
 {"code": "<verification code here>"}
 ```
 

diff --git a/docs/fidesops/mkdocs.yml b/docs/fidesops/mkdocs.yml
@@ -19,7 +19,6 @@ nav:
           - User Management: ui/user_management.md
   - How-To Guides:
       - View Available Connection Types: guides/connection_types.md
-      - Configure Email Communications: guides/email_communications.md
       - Annotate Complex Fields: guides/complex_fields.md
       - Configure Data Masking: guides/masking_strategies.md
       - Configure Storage Destinations: guides/storage.md
@@ -28,7 +27,7 @@ nav:
       - Configure OneTrust Integration: guides/onetrust.md
       - Preview Query Execution: guides/query_execution.md
       - Data Rights Protocol: guides/data_rights_protocol.md
-      - Configure Email Connectors: guides/email_connectors.md
+      - Configure Automatic Emails: guides/email_communications.md
   - SaaS Connectors:
       - Connect to SaaS Applications: saas_connectors/saas_connectors.md
       - SaaS Configuration: saas_connectors/saas_config.md