Overview

By default, Databricks sends operational emails such as deprecation notices, maintenance alerts, and feature change notifications to workspace admins. If your organization uses a shared distribution list (DL) or team alias to manage these emails, you can configure a custom recipient address on each workspace.

This article explains three ways to do this:

• Option 1: Configure using Terraform (recommended for enterprise customers managing infrastructure as code).
• Option 2: Update a single workspace using the Databricks REST API directly.
• Option 3: Update many workspaces at once using a Python command-line tool.

Supported clouds: AWS, GCP

Before you begin

• You must be a workspace admin for each workspace you want to configure.
• For Options 1 and 4, you need an account-level OAuth service principal that is a workspace admin on all target workspaces. See the Service principals documentation (AWS | GCP) for setup instructions.

Option 1: Configure using Terraform

Use this option if your organization manages Databricks infrastructure using Terraform. This is the recommended approach for enterprise customers who want to configure many workspaces consistently through code.

This option uses the databricks_workspace_setting_v2 resource in the official Databricks Terraform provider.

Set the operational email recipient on a workspace

resource "databricks_workspace_setting_v2" "operational_email" {
  name = "operationalEmailCustomRecipient"

  operational_email_custom_recipient = {
    email = "your-dl@company.com"
  }
}

Replace your-dl@company.com with your distribution list or team email address.

Configure across multiple workspaces

If you manage multiple workspaces in your Terraform configuration, use the provider_config block to specify which workspace each resource applies to:

resource "databricks_workspace_setting_v2" "workspace_a_email" {
  name = "operationalEmailCustomRecipient"

  operational_email_custom_recipient = {
    email = "your-dl@company.com"
  }

  provider_config = {
    workspace_id = "1234567890123456"
  }
}

resource "databricks_workspace_setting_v2" "workspace_b_email" {
  name = "operationalEmailCustomRecipient"

  operational_email_custom_recipient = {
    email = "your-dl@company.com"
  }

  provider_config = {
    workspace_id = "9876543210654321"
  }
}

Remove the custom recipient

To revert to workspace-admin-only delivery, remove the resource from your Terraform configuration and run terraform apply, or set email to an empty string:

resource "databricks_workspace_setting_v2" "operational_email" {
  name = "operationalEmailCustomRecipient"

  operational_email_custom_recipient = {
    email = ""
  }
}

Import an existing setting into Terraform state

If the setting was previously configured outside Terraform, import it so Terraform can manage it going forward. For Terraform v1.5 and later:

import {
  id = "operationalEmailCustomRecipient"
  to = databricks_workspace_setting_v2.operational_email
}

For older versions of Terraform:

terraform import databricks_workspace_setting_v2.operational_email "operationalEmailCustomRecipient"

For full provider documentation, see the databricks_workspace_setting_v2 resource on the Terraform Registry.

Option 2: Configure a single workspace via REST API

Use this option if you want to update one workspace at a time using curl or any HTTP client.

Step 1: Get the current setting

Run the following command, replacing <workspace-url> with your workspace hostname (for example, dbc-abc123.cloud.databricks.com) and <personal-access-token> with a valid Databricks personal access token:

curl -X GET \
  "https://<workspace-url>/api/2.1/settings/operationalEmailCustomRecipient" \
  -H "Authorization: Bearer <personal-access-token>"

Example response:

{
  "name": "operationalEmailCustomRecipient",
  "operational_email_custom_recipient": {
    "email": "current-address@company.com"
  },
  "etag": "abc123etag"
}

Copy the etag value from the response; you need it for the next step.

Step 2: Set or update the recipient

Run the following command, replacing <etag-value> with the value from Step 1 and <your-dl@company.com> with the email address or distribution list you want to use:

curl -X PATCH \
  "https://<workspace-url>/api/2.1/settings/operationalEmailCustomRecipient?settingName=operationalEmailCustomRecipient&etag=<etag-value>" \
  -H "Authorization: Bearer <personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "operationalEmailCustomRecipient",
    "operational_email_custom_recipient": {
      "email": "<your-dl@company.com>"
    },
    "field_mask": "operational_email_custom_recipient.email"
  }'

What is the etag? The etag is a version token. The API requires you to pass the current etag when making a change so that two updates cannot accidentally overwrite each other at the same time.

To remove the custom recipient and revert to workspace-admin-only delivery, set "email" to an empty string ("").

Step 3: Verify the change

Repeat the GET call from Step 1 and confirm the response shows your new address.

For full API documentation, see the Settings API keys reference (AWS | GCP).

Option 3: Single-workspace configuration using Python

Use this option if you only need to configure one workspace at a time. This requires no installation beyond the Databricks CLI, curl, and python3.

Save the script below as set_operational_email.sh and make it executable:

chmod +x set_operational_email.sh

# Read current setting
./set_operational_email.sh <profile> --get

# Set the recipient
./set_operational_email.sh <profile> your-dl@company.com

# Remove the custom recipient
./set_operational_email.sh <profile> --clear

Replace <profile> with the name of a Databricks CLI profile that is authenticated to the target workspace.

Script (set_operational_email.sh):

#!/usr/bin/env bash
# Set (or clear) the Operational Email custom recipient on a single Databricks workspace.
# Requires: Databricks CLI (authenticated to the workspace profile), python3, curl.
# Note: AWS and GCP only — Azure workspaces return 404 for this setting.
#
# Usage:
#   ./set_operational_email.sh <profile> <email>     # set recipient
#   ./set_operational_email.sh <profile> --get       # read current value
#   ./set_operational_email.sh <profile> --clear     # remove recipient

set -euo pipefail
[[ $# -eq 2 ]] || { echo "usage: $0 <profile> <email|--get|--clear>" >&2; exit 2; }
PROFILE="$1"; ACTION="$2"
SETTING="operationalEmailCustomRecipient"

HEADER_FILE=""
cleanup() { [[ -n "$HEADER_FILE" && -f "$HEADER_FILE" ]] && rm -f "$HEADER_FILE"; }
trap cleanup EXIT INT TERM

HOST=$(databricks auth env --profile "$PROFILE" 2>/dev/null \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['env']['DATABRICKS_HOST'])" 2>/dev/null || true)
[[ -z "${HOST:-}" ]] && HOST=$(databricks auth describe -p "$PROFILE" -o json 2>/dev/null \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['details']['host'])")
HOST="${HOST%/}"

TOKEN=$(databricks auth token -p "$PROFILE" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
HEADER_FILE=$(mktemp); chmod 600 "$HEADER_FILE"
printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" > "$HEADER_FILE"; unset TOKEN

URL="$HOST/api/2.1/settings/$SETTING"
CURL=(curl -sS --fail-with-body --config "$HEADER_FILE")

patch_body() {
  EMAIL="$1" python3 -c '
import json, os
print(json.dumps({
  "name": "operationalEmailCustomRecipient",
  "operational_email_custom_recipient": {"email": os.environ["EMAIL"]},
  "field_mask": "operational_email_custom_recipient.email",
}))'
}

case "$ACTION" in
  --get)
    "${CURL[@]}" "$URL"; echo ;;
  --clear)
    "${CURL[@]}" -X PATCH "$URL" -H "content-type: application/json" \
      --data "$(patch_body '')"; echo ;;
  --*)
    echo "usage: $0 <profile> <email|--get|--clear>" >&2; exit 2 ;;
  *)
    EMAIL="$ACTION"
    [[ "$EMAIL" =~ ^[^@[:space:]]+@[^@[:space:]]+\.[^@[:space:]]+$ ]] \
      || { echo "error: '$EMAIL' is not a valid email" >&2; exit 2; }
    "${CURL[@]}" -X PATCH "$URL" -H "content-type: application/json" \
      --data "$(patch_body "$EMAIL")"; echo
    echo "Verify:"; "${CURL[@]}" "$URL"; echo ;;
esac

Option 4: Bulk-configure across many workspaces using a Python tool

Use this option if you manage a Databricks account with many workspaces and want to configure all of them in one command without using Terraform.

This tool authenticates as an account-level service principal, enumerates your workspaces via the account API, and calls the Settings v2 REST endpoint on each one in parallel.

Step 1: Set up authentication

The recommended approach is an account-level OAuth service principal. Set the following environment variables before running any commands:

export DATABRICKS_ACCOUNT_ID="<your-account-id>"
export DATABRICKS_CLIENT_ID="<service-principal-client-id>"
export DATABRICKS_CLIENT_SECRET="<service-principal-secret>"

You can find your account ID in the Databricks account console (top right corner).

Alternatively, use an account personal access token (PAT):

export DATABRICKS_ACCOUNT_ID="<your-account-id>"
export DATABRICKS_TOKEN="<your-account-pat>"

Step 2: Preview your changes first (recommended)

Always use --dry-run before making changes. This shows you exactly what would happen without writing anything:

operational-emails set --email your-dl@company.com --all --dry-run

The output lists every workspace and whether it would be updated or left unchanged.

Step 3: Apply the change

When you are satisfied with the preview, run without --dry-run:

# Set the recipient on all workspaces
operational-emails set --email your-dl@company.com --all
# Set on specific workspaces by ID or name
operational-emails set --email your-dl@company.com \
  --workspace-ids 1234567890123456,prod-analytics
# Set on workspaces matching a filter (region, name pattern, and/or status)
operational-emails set --email your-dl@company.com \
  --region us-west-2 --name-pattern 'prod-*'

The tool is idempotent: if a workspace already has the correct address, it is skipped and reported as "Unchanged."

Other useful commands

Read the current recipient on all workspaces:

operational-emails get --all

Audit for drift (find workspaces that do not match your expected address):

operational-emails audit --email your-dl@company.com --all

Remove the custom recipient (revert to workspace-admin-only delivery):

operational-emails clear --all

Fix 403 errors: the service principal is not a workspace admin

If you see 403 Unauthorized errors for some workspaces, the service principal does not have workspace admin rights on those workspaces. To grant access:

# Preview first
operational-emails ensure-admin --workspace-ids <failed-workspace-ids> --dry-run

# Then apply
operational-emails ensure-admin --workspace-ids <failed-workspace-ids> --yes

Alternatively, grant access manually in the Databricks account console under Workspaces > [workspace name] > Permissions.

After granting access, re-run your original set command.

Related resources

• Settings API keys reference (AWS | GCP)
• databricks_workspace_setting_v2 (Terraform Registry)
• Service principals (AWS | GCP)
• Personal access tokens (AWS | GCP)