> For the complete documentation index, see [llms.txt](https://docs.docs-dispatcher.io/docs-dispatcher/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/email.md).

# Email Dispatch

Send an e-mail with a templated body — optionally with a generated document attached, in a single call.

## Two patterns

| You want…                                           | Endpoint                                      | Pattern                                    |
| --------------------------------------------------- | --------------------------------------------- | ------------------------------------------ |
| A standalone e-mail (body templated, no attachment) | `POST /api/email`                             | Single service                             |
| An e-mail **with** a generated PDF attached         | `POST /api/file/email`                        | Composed (file → email)                    |
| An invoice e-mailed by the provider itself          | `POST /api/invoicing` with `sendByEmail=true` | Use provider e-mail, not Docs-Dispatcher's |

This page covers the first two. For invoice e-mails sent by the provider, see [Invoice recipe](/docs-dispatcher/how-to-recipes/invoice.md).

## Prerequisites

* A Docs-Dispatcher account ([authentication](/docs-dispatcher/authentication/basic-auth.md))
* An e-mail template registered in your account (HTML or text)
* SMTP configuration set up at the company / user level

## Standalone e-mail

{% stepper %}
{% step %}

### Validate

```bash
curl -X POST https://api.docs-dispatcher.io/api/email/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  --data @email.json
```

{% endstep %}

{% step %}

### Dispatch

```bash
curl -X POST https://api.docs-dispatcher.io/api/email \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  --data @email.json
```

{% endstep %}
{% endstepper %}

### Minimal payload (`email.json`)

```json
{
  "from": "noreply@your-domain.com",
  "to": ["recipient@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Welcome to our service",
  "template": {
    "id": 456,
    "data": {
      "username": "Jane",
      "activationLink": "https://your-app.com/activate?token=xyz"
    }
  }
}
```

| Field                          | Required | Notes                                                                                                 |
| ------------------------------ | :------: | ----------------------------------------------------------------------------------------------------- |
| `from`                         |     ✅    | Sender — must match the SMTP configuration's allowed senders                                          |
| `to`                           |     ✅    | Recipient list                                                                                        |
| `cc`, `bcc`                    |     —    | Optional cc / bcc lists                                                                               |
| `subject`                      |     ✅    | Static subject; for templated subject, include it in `template.data` and reference it in the template |
| `template.id`, `template.data` |     ✅    | Resolved into the e-mail body                                                                         |

## With a generated PDF attached

Use the composed endpoint `POST /api/file/email`: Docs-Dispatcher generates the file from the file template, then sends it as an attachment via the e-mail template.

```bash
curl -X POST https://api.docs-dispatcher.io/api/file/email \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  --data @composite.json
```

### Composite payload (`composite.json`)

```json
{
  "fileContent": {
    "templateName": "report-template",
    "data": { "month": "April", "metrics": { /* … */ } }
  },
  "email": {
    "from": "reports@your-domain.com",
    "to": ["client@example.com"],
    "subject": "Your monthly report",
    "template": {
      "id": 456,
      "data": { "month": "April" }
    }
  }
}
```

The same composition is available as `/api/invoicing/email`, `/api/esign/email`, etc.

## In SDKs

{% tabs %}
{% tab title="Node SDK" %}

```typescript
const email = new DocsDispatcher.Service.MailDispatcher({
  from: 'noreply@your-domain.com',
  to: ['recipient@example.com'],
  subject: 'Welcome',
  templateName: 'welcome-email',
  data: { username: 'Jane' },
})

await dd.withBaseService(email).dispatch()
```

{% endtab %}

{% tab title="PHP SDK" %}

```php
$factory = (new Sdk\ServiceMediator())
    ->addService(new Sdk\Service\EmailService([
        'from' => 'noreply@your-domain.com',
        'to'   => ['recipient@example.com'],
        'subject' => 'Welcome',
        'template' => ['id' => 456, 'data' => ['username' => 'Jane']],
    ]));

$client->executeRequest($factory, 'application/json');
```

{% endtab %}

{% tab title="Java SDK" %}

```java
EmailRequest req = new EmailRequest();
req.setFrom("noreply@your-domain.com");
req.setTo(List.of("recipient@example.com"));
req.setSubject("Welcome");
// … set template

endUserApi.dispatchersDispatch(Service.EMAIL, new CompositeRequest().email(req));
```

{% endtab %}
{% endtabs %}

## Common errors

| Status | `error`                 | Fix                                                                      |
| ------ | ----------------------- | ------------------------------------------------------------------------ |
| 417    | `expectation_failed`    | `from` not whitelisted in SMTP config, or `to` empty                     |
| 500    | `distant_service_error` | SMTP server rejected the message — check the `message` for the SMTP code |

## Webhooks

E-mail delivery / open / click webhooks are **not currently wired** in Docs-Dispatcher — see [Email webhook events](/docs-dispatcher/webhooks/email.md).

## Where to go next

* [**Invoice recipe**](/docs-dispatcher/how-to-recipes/invoice.md) — invoices e-mailed by the provider
* [**Async flow**](/docs-dispatcher/how-to-recipes/async-flow.md) — for large e-mail batches
* [**Validate then send**](/docs-dispatcher/how-to-recipes/validate-send.md) — always validate first


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.docs-dispatcher.io/docs-dispatcher/how-to-recipes/email.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.