# 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](/content/docs/platform/configuration/configuration/index.html) 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)](https://documentation.mailgun.com/en/latest/quickstart-sending.html#send-via-api) from your Mailgun Dashboard or;
- Generate a [Mailgun Domain Sending Key (opens in a new tab)](https://documentation.mailgun.com/en/latest/api-intro.html#authentication-1).

## 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:

**Default Messaging Provider Response**

```
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}}"
}'
```

The `{{MAILGUN_API_KEY}}` is either your Mailgun Private API Key or Domain Sending Key as described in [this section](/content/docs/platform/messaging/mailgun-email#generate-your-mailgun-api-key/index.html).

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:

**Default Messaging Provider Response**

```
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 system notifications. To do this you must update Fides' system-wide settings to ensure that your Mailgun service is selected. You may also configure what kinds of notifications Fides will send.

Below is a list of the notification configurations that can be set:

| Name | Type | Default | Description |
| :-- | :-- | :-- | :-- |
| `notification_service_type` | string | `None` | Sets the notification service type used to send notifications. Accepts `"mailgun"`, `"twilio_text"`, `"twilio_email"`, or `"aws_ses"`. |
| `send_request_completion_notification` | boolean | `False` | When set to `True`, sends notification subject when their request has been completed. |
| `send_request_receipt_notification` | boolean | `False` | When set to `True`, sends notification to subject to confirm receipt of their request. |
| `send_request_review_notification` | boolean | `False` | When set to `True`, sends notification to subject to confirm their request is in review. |
| `subject_identity_verification_required` | boolean | `False` | Whether privacy requests require user identity verification. |

## 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
  }
}'
```

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 setting `execution.subject_identity_verification_required` to `true`. Learn more about [Subject Identify Verification](/content/docs/privacy-requests/guides/identity-verification/index.html) here.

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

**Fides Configuration Update Response**

```
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".

**Fides Configuration Update Response**

```
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.

When sending emails Fides will check to see if the `fides` template exists and use it. If a fides template is not found, the message will be sent using the the generic Fides email template.

### Create a Mailgun fides Template

For detailed step-by-step instructions on configuring the template, please visit the [configure email style customization](/content/docs/privacy-requests/guides/configure-email/email-style/index.html) 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)](https://documentation.mailgun.com/en/latest/user_manual.html#templates) 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.