# Configure Twilio (SendGrid) for Email

This document explains how to configure email notification and messaging services with Twilio (SendGrid) and Fides.

## Prerequisites

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

- A valid Twilio (SendGrid) 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 Twilio (SendGrid) API Key

In order to configure Twilio (SendGrid) as a messaging provider for Fides you will need a Twilio API Key. You can do this by following the [Twilio documentation (opens in a new tab)](https://www.twilio.com/docs/iam/keys/api-key) to create an API key here.

## Example: Set Twilio (SendGrid) as the default messaging provider

To set Twilio (SendGrid) as the default messaging provider, make a **PUT** request to the `api/v1/messaging/default` endpoint as follows:

PUT /api/v1/messaging/default

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

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 `twilio_email` and `{{TWILIO_FROM_EMAIL}}` is the "From Email" you'd like to send messages from.

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

Default Messaging Provider Response

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "service_type": "twilio_email",
    "details": {
        "twilio_email_from": "{{TWILIO_FROM_EMAIL}}"
    },
    "name": "Default Messaging Config [twilio_email]",
    "key": "default_messaging_config_twilio_email"
}
```

## Example: Add Twilio (SendGrid) API Key

Next, you can add the API key generated in Twilio (SendGrid) to your Twilio configuration by making a **PUT** request to the `api/v1/messaging/default/twilio_email/secret` endpoint as follows:

PUT /api/v1/messaging/default/twilio_email/secret

```
curl '{{FIDES_URL}}/api/v1/messaging/default/twilio_email/secret' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "twilio_api_key": "{{TWILIO_API_KEY}}"
}'
```

The `{{TWILIO_API_KEY}}` is your Twilio API Key as created in [this section](/content/docs/platform/messaging/twilio-email#generate-your-twilio-sendgrid-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: default_messaging_config_twilio_email.",
    "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 Twilio 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:

PATCH /api/v1/config

```
curl '{{FIDES_URL}}/api/v1/config' \
-X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
  "notifications": {
    "notification_service_type" : "twilio_email",
    "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 `twilio_email` and for each of the notifications you wish to send via Twilio, 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": "twilio_email"
    },
    "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`.

GET /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 twilio_email is fully configured"
}
```