Configure Mailgun for Email

This document explains how to configure email notification and messaging services with Mailgun and Fides.

Prerequisites

In order to complete this, you will need the following:

• A valid Mailgun account with which to send emails.
• Ability to access and update Fides system config variables for your Fides installation. Read about config variables here.
• Fides OAuth access token with the following scopes.
  • messaging:read: Read an existing messaging configuration.
  • messaging:create_or_update: Create or update messaging configuration.
  • messaging:delete: Delete a messaging configuration.
  • config:read: Read Fides system configurations.
  • config:update: Update Fides system configurations.

Generate your Mailgun API Key

In order to configure Mailgun as a messaging provider for Fides you will need a Mailgun API Key. You can either:

• Use your default Mailgun Private API Key (opens in a new tab) from your Mailgun Dashboard or;
• Generate a Mailgun Domain Sending Key (opens in a new tab).

Example: Set Mailgun as the default messaging provider

To set Mailgun as the default messaging provider, make a PUT request to the api/v1/messaging/default endpoint as follows:

curl '{{FIDES_URL}}/api/v1/messaging/default' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "service_type": "mailgun",
    "details": {
        "domain": "{{MAILGUN_DOMAIN}}"
    }
}'

In the above example {{FIDES_URL}} is the URL to your Fides server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Fides access token. The request Content-Type is application/json.

The service_type is mailgun and {{MAILGUN_DOMAIN}} is the domain associated with your Mailgun account.

The response to this request will return the configuration for the default messaging provider, including your domain and a key as shown below:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "service_type": "mailgun",
    "details": {
        "is_eu_domain": false,
        "api_version": "v3",
        "domain": "{{MAILGUN_DOMAIN}}"
    },
    "name": "string",
    "key": "TNSm_.......K6je4ei"
}

Example: Add Mailgun API Key

Next, you can add the API key generated in Mailgun to your Mailgun configuration by making a PUT request to the api/v1/messaging/default/mailgun/secret endpoint as follows:

curl '{{FIDES_URL}}/api/v1/messaging/default/mailgun/secret' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "mailgun_api_key": "{{MAILGUN_API_KEY}}"
}'

In the above example {{FIDES_URL}} is the URL to your Fides server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Fides access token. The request Content-Type is application/json.

The {{MAILGUN_API_KEY}} is either your Mailgun Private API Key or Domain Sending Key as described in this section.

The response to this request will be a confirmation message that the secret has been updated for the configuration identified by the key as shown in this example:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "msg": "Secrets updated for MessagingConfig with key: TNSm_.......K6je4ei.",
    "test_status": null,
    "failure_reason": null
}

Messaging Config Variables

Fides allows you to configure which messaging service is used to send each system notification. To do this you must update Fides' system-wide settings to ensure that your Mailgun service is selected for each notification. Below is a list of the notification cofigurations that can be set:

Example: Set Messaging Config Variables

You can update your Fides messaging configuration by making a PATCH request to the api/v1/config endpoint as follows:

curl '{{FIDES_URL}}/api/v1/config' \
-X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
  "notifications": {
    "notification_service_type" : "mailgun",
    "send_request_receipt_notification": true,
    "send_request_review_notification": true,
    "send_request_completion_notification": true
  },
  "execution": {
    "subject_identity_verification_required": true
  }
}'

In the above example {{FIDES_URL}} is the URL to your Fides server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Fides access token. The request Content-Type is application/json.

The notification_service_type value is mailgun and for each of the notifications you wish to send via Mailgun, set their value to true. You can also enable or disable subject identify verification on privacy requests here by settting execution.subject_identity_verification_required to true. Learn more about Subject Identify Verification here.

The response to this request will confirm the service type and the current status for each notification as shown in the example below:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "notifications": {
        "send_request_completion_notification": true,
        "send_request_receipt_notification": true,
        "send_request_review_notification": true,
        "notification_service_type": "mailgun"
    },
    "execution": {
        "subject_identity_verification_required": true
    }
}

Check the messaging configuration status

To check that your messaging configuration has been fully configured, you can invoke the status endpoint at /api/v1/messaging/default/status.

curl '{{FIDES_URL}}/api/v1/messaging/default/status' \
-X GET \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d ''

If everything is correctly configured you will receive a response similar to the example below with config_status of "configured".

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "config_status": "configured",
    "detail": "Active default messaging service of type mailgun is fully configured"
}

Creating and Using Templates

Mailgun can be setup to either use customized Mailgun templates, or the generic Fides template.

Create a Mailgun fides Template

For detailed step-by-step instructions on configuring the template, please visit the configure email style customization section. Below is a brief summary on making the template.

1. In Mailgun create a template named fides. You can follow Mailgun's documentation on creating templates (opens in a new tab) here.
2. Templates can be customized to your requirements, just remember it must contain a {{{fides_email_body}}} variable as this is where the Fides email text will be placed.

Note: In order to use this custom fides template you must use the Mailgun Private API Key and not a Mailgun Domain Sending Key.

Using the Default Template

If you do not create a fides template in Mailgun, Fides will automatically use the built-in default template.

Note: you can use either the Mailgun Private API key or Domain Sending Key with the default template.