# Email | DRE

> The email destination: SMTP settings and options.

You're reading the docs for DRE 0.4 (v0.4.4). [This page for 0.5](https://getdre.com/docs/plugin-email/) · [New in 0.5](https://getdre.com/docs/new-in-0.5/)

# Email

Email, with the output attached: the `email` destination, from the `email` package. Declare the package once in `dependencies.yml`; DRE installs it on demand:

dependencies.yml

```yaml
plugins:
  - email
```

### Profile fields

Set in `profiles.yml`, under `destinations:`, in a target with `type: email`.

Field

Default

Notes

`host` (required)

SMTP server host.

`port`

SMTP port (587 for starttls, 465 for implicit TLS)

`tls`

`starttls`

Starttls, implicit or none. One of `starttls`, `implicit`, `none`.

`username`

SMTP username.

`password`

SMTP password. Secret: use `env_var()`.

`from` (required)

Sender address, e.g. “Reports [reports@example.com](mailto:reports@example.com)”.

`to`

Default recipients when a report names none.

`cc`

Default cc recipients.

`bcc`

Default bcc recipients.

`max_attachment_mb`

`20`

Largest total attachment size to send.

`tls_accept_invalid_certs`

`false`

Accept a self-signed server certificate.

`connect_timeout`

`30s`

How long to wait for a connection (`30s`, `2m`, or seconds) A duration (`30s`, `2m`) or seconds.

`timeout`

`60s`

How long a read or write may make no progress before it fails. A duration (`30s`, `2m`) or seconds.

`retries`

`3`

How many times to try again after a temporary error (0: never)

### Options

Set in the report’s `output.destination` entry.

Option

Type

Default

Notes

`to`

strings

Recipients: an address, a comma-separated string or a list.

`cc`

strings

Cc recipients.

`bcc`

strings

Bcc recipients.

`subject`

string

The subject line.

`body`

string

The message text.

`attachment_name`

string

The attachment’s file name (single-file outputs)

## Notes

Sends the output as attachments on one email over SMTP. If a report produces several files, they all go on the same message.

Profile fields: `host`, `port` (587 for `starttls`, 465 for `implicit`, 25 for `none`), `tls` (`starttls` by default, `implicit` or `none`), `username` and `password`, and `from` (`reports@example.com` or `"Reports <reports@example.com>"`). Optional fields:

-   `to`, `cc`, `bcc`: default recipients.
-   `max_attachment_mb`: default 20.
-   `tls_accept_invalid_certs`: allows a self-signed server certificate.

Destination options:

Option

Meaning

`to`, `cc`, `bcc`

An address, a comma-separated string or a list. Each one replaces the profile’s default.

`subject`

Default `Report: <file names>`.

`body`

Plain text. Default `Attached: <file names>`.

`attachment_name`

Renames the attachment. Only allowed when the output is a single file.

```yaml
destination:
  - profile: finance_mail
    to: ["{{ var('client') }}-finance@example.com"]
    bcc: archive@example.com
    subject: "Monthly report {{ run.date.iso }}"
    body: "Attached is this month's report for {{ var('client') }}."
```

The plugin checks the email before it connects. It fails without sending anything when there are no recipients, an address is invalid, an option is unknown, or the attachments exceed `max_attachment_mb`. The password is never logged.

**Email always attaches the file.** DRE can’t send a link instead of the file, and it doesn’t create download links (no presigned URLs). Most mail servers cap a message at 20–25 MB, so a bigger output can’t go by email. Deliver it to object storage or another destination, and tell people where it is yourself; a location written into `body` only helps readers who can already open it. In a list of destinations an email entry still attaches the output, so an oversized output fails that entry (the others are delivered) and the run fails.

**Messages** (email 1.1.0): for a [`message`](https://getdre.com/docs/v0.4/plugins/#the-message-format) output, the message is the email: an HTML body with a plain-text alternative, and the subject is `subject:`, else the message’s title. `body:` doesn’t apply. `attach: [<output>]` on the entry attaches those outputs’ files, under the same `max_attachment_mb` check, so one email carries the headline and the workbook:

```yaml
output:
  - name: workbook
    format: xlsx
    queries: [detail]
  - name: headline
    format: message
    queries: [headline]
    destination:
      - {profile: finance_mail, to: finance@example.com, attach: [workbook]}
```

## Configure the sender before adding recipients

Use email for a workbook that recipients need as an attachment. Starting with the complete [monthly finance report](https://github.com/get-dre/dre/blob/v0.4.4/examples/monthly-finance/), configure the SMTP identity separately:

profiles.yml

```yaml
destinations:
  finance_mail:
    targets:
      dev: {deliver: false}
      prod:
        type: email
        host: smtp.example.com
        port: 587
        tls: starttls
        username: reports@example.com
        password: "{{ env_var('DRE_SECRET_SMTP_PASSWORD') }}"
        from: "Reports <reports@example.com>"
        to: finance@example.com
        max_attachment_mb: 20
```

The destination example above overrides those default recipients; omitted recipient options keep their profile defaults. Preview locally, then validate with `--target prod` before a real send. `invalid-destination-option` identifies bad addresses or options; `delivery-failed` can mean SMTP authentication, server policy or an oversized attachment. Lower row counts or deliver a large file to storage instead. `attachment_name` applies only to a single-file output. See [messages](https://getdre.com/docs/v0.4/messages/), [destination keys](https://getdre.com/docs/v0.4/reference-report/#outputdestination), [error codes](https://getdre.com/docs/v0.4/reference-error-codes/) and [destination](https://getdre.com/docs/v0.4/glossary/#destination).

[Previous  
DuckDB](https://getdre.com/docs/v0.4/plugin-duckdb/)[Next  
Fixed-width text](https://getdre.com/docs/v0.4/plugin-fixed_width/)