> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMTP Settings

> Configure SMTP settings for your data app so scheduled reports can be sent by email.

Set or update the SMTP configuration used to send scheduled reports and other emails for your data app. The API validates the connection before saving; if the credentials or server are invalid, the request fails and settings are not stored.

<Note>
  You can also configure email in the UI: **Settings → Embed Settings → Email Settings**. This API is for automation and integration. See [Email Settings for Scheduled Reports](/guides/preview-of-dashboards/email-settings-for-scheduled-reports) for the UI flow.
</Note>

## Endpoint

```
PUT https://api.usedatabrain.com/api/v2/data-app/smtp-settings
```

## Authentication

All requests must include your **data app API key** in the `Authorization` header. See the [data app creation guide](/guides/datasources/create-a-data-app) and the [API Token guide](/developer-docs/helpers/api-token).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your data app API key.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request Body

<ParamField body="host" type="string" required>
  SMTP server hostname (e.g. `smtp.example.com`).
</ParamField>

<ParamField body="port" type="number" required>
  SMTP server port as integer (e.g. `587` for STARTTLS, `465` for implicit SSL).
</ParamField>

<ParamField body="username" type="string" required>
  SMTP authentication username.
</ParamField>

<ParamField body="password" type="string" required>
  SMTP authentication password.
</ParamField>

<ParamField body="fromAddress" type="string" required>
  Sender email address. Must be a valid email format (e.g. `noreply@example.com`).
</ParamField>

<ParamField body="replyToAddress" type="string" required>
  Reply-to email address. Must be a valid email format.
</ParamField>

<ParamField body="secure" type="boolean" required>
  Whether to use TLS/SSL for the connection. Use `true` for port 465; use `false` for port 587 with STARTTLS.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <ResponseField name="data.success" type="boolean">
    `true` when settings were saved successfully.
  </ResponseField>
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request PUT \
      --url 'https://api.usedatabrain.com/api/v2/data-app/smtp-settings' \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "host": "smtp.example.com",
        "port": 587,
        "username": "smtp-user",
        "password": "your-password",
        "fromAddress": "noreply@example.com",
        "replyToAddress": "support@example.com",
        "secure": false
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/smtp-settings', {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        host: 'smtp.example.com',
        port: 587,
        username: 'smtp-user',
        password: 'your-password',
        fromAddress: 'noreply@example.com',
        replyToAddress: 'support@example.com',
        secure: false,
      }),
    });
    const result = await response.json();
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/smtp-settings"
    headers = {
        "Authorization": "Bearer dbn_live_abc123...",
        "Content-Type": "application/json",
    }
    payload = {
        "host": "smtp.example.com",
        "port": 587,
        "username": "smtp-user",
        "password": "your-password",
        "fromAddress": "noreply@example.com",
        "replyToAddress": "support@example.com",
        "secure": False,
    }

    response = requests.put(url, headers=headers, json=payload)
    data = response.json()
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success theme={"dark"}
    {
      "data": {
        "success": true
      }
    }
    ```

    ```json Error – Validation theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"fromAddress\" must be a valid email"
      }
    }
    ```

    ```json Error – SMTP test failed theme={"dark"}
    {
      "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "SMTP connection test failed"
      }
    }
    ```

    ```json Error – Invalid API key theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "invalid or expired API KEY, data app not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## Error codes

| Error Code                 | HTTP Status | Description                                                        |
| -------------------------- | ----------- | ------------------------------------------------------------------ |
| `INVALID_DATA_APP_API_KEY` | 400         | Missing or invalid data app API key                                |
| `INVALID_SERVICE_TOKEN`    | 400         | Invalid or expired token; cannot resolve company context           |
| `INVALID_REQUEST_BODY`     | 400         | Invalid or missing body fields (e.g. invalid email, missing host)  |
| `INTERNAL_SERVER_ERROR`    | 400 / 500   | SMTP connection test failed (400) or unexpected server error (500) |

## Related

<CardGroup cols={2}>
  <Card title="Email Settings for Scheduled Reports" href="/guides/preview-of-dashboards/email-settings-for-scheduled-reports">
    Configure email in the UI
  </Card>

  <Card title="Whitelist Domains" href="/developer-docs/helpers/api-reference/whitelist-domains">
    Manage embedding domains
  </Card>
</CardGroup>