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

# Custom SMTP

> Read, update, and test the custom SMTP mailbox used to deliver client reports.

Manage the custom SMTP mailbox that SnowSEO uses to send client reports and audit emails, so they arrive from your own domain instead of SnowSEO's.

<Note>
  Requires **managed** (admin/owner) access to the brand. Custom SMTP also requires the **Scale** plan (or AppSumo tier 3+); otherwise every route returns `403`.
</Note>

The `GET` response is **masked** — the stored password is never returned. Instead a `hasPassword` boolean tells you whether a password is on file.

### GET response fields

The response is `{ "success": true, "data": { ... } }`, where `data` contains:

| Field         | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `enabled`     | Whether custom SMTP is turned on.                                        |
| `host`        | SMTP host, or `null`.                                                    |
| `port`        | SMTP port, or `null`.                                                    |
| `encryption`  | One of `ssl`, `tls`, or `none`. Defaults to `tls`.                       |
| `user`        | SMTP username, or `null`.                                                |
| `fromName`    | Display name on outgoing mail, or `null`.                                |
| `fromEmail`   | From address, or `null`.                                                 |
| `replyTo`     | Reply-to address, or `null`.                                             |
| `hasPassword` | `true` when a password is stored. The password itself is never returned. |

***

## Update SMTP

`PATCH /v3/settings/brand/smtp`

Update the SMTP credentials. Only the fields you send change; the rest keep their stored values. Returns `{ "success": true, "data": { ... } }` with the same masked `data` shape as `GET`.

| Field        | Description                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `teamId`     | Brand (team) to update.                                                                                         |
| `enabled`    | Turn custom SMTP on/off.                                                                                        |
| `host`       | SMTP host, or `null`.                                                                                           |
| `port`       | Integer between `1` and `65535`, or `null`.                                                                     |
| `encryption` | `ssl`, `tls`, or `none`.                                                                                        |
| `user`       | SMTP username, or `null`.                                                                                       |
| `password`   | Plaintext password to store (encrypted at rest). Omit, send `null`, or send `""` to keep the existing password. |
| `fromName`   | Display name, or `null`.                                                                                        |
| `fromEmail`  | From address (must be a valid email), or `null`.                                                                |
| `replyTo`    | Reply-to address (must be a valid email), or `null`.                                                            |

<Warning>
  Sending `password` as `null` or an empty string does **not** clear the stored password — it keeps the existing one. Invalid `fromEmail`/`replyTo` values, an out-of-range `port`, or an unknown `encryption` are rejected with `400`.
</Warning>

***

## Test SMTP

`POST /v3/settings/brand/smtp/test`

Verify the saved SMTP configuration by opening a connection, and optionally send a test message.

| Field       | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `teamId`    | Brand (team) whose saved config to test.                                              |
| `sendTest`  | When `true`, also send a test email after verifying.                                  |
| `testEmail` | Recipient for the test email. Required (and must be valid) when `sendTest` is `true`. |

On success the response is `{ "success": true }`. On failure it returns `{ "success": false, "error": "…" }` with a friendly hint — for example, an SSL/TLS mismatch suggests using port `465` for SSL or port `587` (STARTTLS) for TLS, and an auth error points at the username/password.


## OpenAPI

````yaml GET /v3/settings/brand/smtp
openapi: 3.0.0
info:
  title: SnowSEO API
  description: API documentation for SnowSEO
  version: 1.0.0
servers:
  - url: https://api.snowseo.com
    description: Production server
security: []
tags:
  - name: Keywords
    description: Keyword research and suggestion end-points
  - name: Onboarding
    description: Brand onboarding and strategy end-points
  - name: Brands
    description: Brand management end-points
  - name: Organizations
    description: Organization and member end-points
  - name: Integrations
    description: Google Search Console and other integrations
  - name: Utilities
    description: Common utility end-points like screenshots and uploads
externalDocs:
  url: https://snowseo.com/docs
  description: Find more info here
paths:
  /v3/settings/brand/smtp:
    get:
      tags:
        - Settings
      summary: Get custom SMTP settings
      description: >-
        Read the org's custom SMTP settings (masked — password never returned).
        Requires white-label access (Scale plan / AppSumo tier 3+).
      parameters:
        - schema:
            type: string
          in: query
          name: teamId
          required: false
          description: Team ID
      responses:
        '200':
          description: Default Response

````