> For the complete documentation index, see [llms.txt](https://apidocs.gsped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.gsped.com/gsped-api-english-version/transactional-emails/transactionalemail.md).

# TransactionalEmail

Endpoint for configuring transactional emails

{% hint style="danger" %}
This endpoint requires a specific contract item\
Check with the sales team whether you can use it.
{% endhint %}

This endpoint lets you configure transactional emails (emails sent when a shipment's status changes) on your own.

Rules are tied to the user making the call and can be configured for the client\_ids (or invoiced\_client\_ids) that the user can manage.\
If two rules for the same client\_id overlap on the same courier and the same status, an error is returned for the second rule being inserted.

Emails can be sent through the *mailchimp* or *gsped* engine (check with Gsped what the differences are and how to obtain any configuration parameters).

## Retrieve a single rule, or all rules if no \[ID] is specified

<mark style="color:blue;">`GET`</mark> `https://api.gsped.it/[INSTANCE]/transactionalEmail/[ID]`

For the description of the response fields, refer to the POST method

#### Path Parameters

| Name | Type    | Description                       |
| ---- | ------- | --------------------------------- |
| ID   | Numeric | ID of the single rule to retrieve |

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

{% tabs %}
{% tab title="200: OK Rules retrieved" %}

```json
{
    "result": [
        {
            "id": "1",
            "user_id": "6",
            "client_id": "390",
            "config": {
                "descrizione": "Regola test",
                "sender_commercial_name": "",
                "order_type_reference": "ddt_alpha",
                "motore": "gsped",
                "from": "noreply@gsped.com",
                "to":"",
                "cc": "",
                "bcc": "",
                "subject": "Oggetto della mail",
                "corrieri": [
                    1
                ],
                "statuses": [
                    17,
                    17.4,
                    17.5,
                    18
                ],
                "dominio_validato": true,
                "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
            }
        },
        {
            "id": "2",
            "user_id": "6",
            "client_id": "391",
            "config": {
                "descrizione": "Template di test per tutti",
                "sender_commercial_name": "",
                "order_type_reference": "ddt_num",
                "motore": "mailchimp",
                "bcc": "",
                "cc": "",
                "from": "noreply@gsped.com",
                "subject": "Mail di test da Gsped",
                "corrieri": [
                    1,
                    2
                ],
                "statuses": [
                    19
                ],
                "apikey": "XXXXXXXXXXX",
                "template_slug": {
                    "*": "test-2",
                    "IT": "test"
                },
                "dominio_validato": false
            }
        },
        {
            ...
        },
        {
            ...
        }
    ],
    "code": 200
}
```

{% endtab %}

{% tab title="404: Not Found Rule not found" %}

```json
{
    "error": "No rules found for id X",
    "code": 404
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

{% endtab %}
{% endtabs %}

## Create a new rule

<mark style="color:green;">`POST`</mark> `https://api.gsped.it/[INSTANCE]/transactionalEmail`

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

#### Request Body

<table><thead><tr><th width="222">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>client_id<mark style="color:red;">*</mark></td><td>Numeric</td><td>The client_id the rule applies to</td></tr><tr><td>config<mark style="color:red;">*</mark></td><td>Object</td><td>The configuration container for this client_id (the following parameters must be part of this key)</td></tr><tr><td>sender_commercial_name</td><td>String</td><td><p>Associated template key:</p><pre><code>[sender_commercial_name]
</code></pre><p><strong>Trade name</strong> (optional) <strong>to enter</strong>, displayed before the logo</p><pre><code>[client_logo]
</code></pre><p>in the email template.</p></td></tr><tr><td>order_type_reference<mark style="color:red;">*</mark></td><td><p><strong><code>NotBlank</code></strong><br></p><p><strong><code>Choice</code></strong><code>([</code><br></p><p><code>'ddt_num',</code><br></p><p><code>'ddt_alpha'</code><br></p><p><code>])</code></p></td><td><p>Associated template keys:</p><pre><code>[ddt_alpha][ddt_num]
</code></pre><p>REQUIRED</p><p><strong>Order reference type</strong> (mandatory choice) to enter, displayed with the shipment status text in the email template.</p></td></tr><tr><td>dominio_validato</td><td>bool</td><td>REQUIRED only for the <em>gsped</em> engine<br>Indicates whether the domain has its DNS records configured according to Gsped's instructions for setting up a custom sender email. If <strong>false</strong>, emails are sent from noreply@gsped.com; if <strong>true</strong>, you can customise the <em>from</em> field.</td></tr><tr><td>motore<mark style="color:red;">*</mark></td><td>String</td><td>Email sending engine<br>Possible values:<br>- <em>gsped</em><br>- <em>mailchimp</em></td></tr><tr><td>logo</td><td>String</td><td>REQUIRED only for the <em>gsped</em> engine<br>Base64 of a png image of max 300x300px to be used in the templates</td></tr><tr><td>from<mark style="color:red;">*</mark></td><td>String</td><td>Email address shown as the sender of the transactional email</td></tr><tr><td>cc</td><td>String</td><td>Optional email address in copy</td></tr><tr><td>bcc</td><td>String</td><td>Optional email address in blind copy</td></tr><tr><td>descrizione<mark style="color:red;">*</mark></td><td>String</td><td>Description of the rule and what it does</td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>String</td><td>Email subject</td></tr><tr><td>apikey</td><td>String</td><td>REQUIRED only for the <em>mailchimp</em> engine<br>The API key for the connection with mailchimp</td></tr><tr><td>corrieri<mark style="color:red;">*</mark></td><td>Array</td><td>List of <a href="/gsped-api-english-version/overview/corrieri-e-servizi.md">courier codes</a> this rule applies to.</td></tr><tr><td>statuses<mark style="color:red;">*</mark></td><td>Array</td><td>List of <a href="/gsped-api-english-version/overview/codici-gsped.md#shipment-status-codes">status codes</a> this rule applies to.</td></tr><tr><td>template_slug</td><td>Object</td><td>REQUIRED only for the mailchimp engine.<br>Key=>value object mapping recipient_country=>template_slug among those created in mailchimp.<br>You can use the <strong>*</strong> character as the country to indicate the "rest of the world", i.e. to use the associated template if no matching country is found among those configured.</td></tr><tr><td>to</td><td>String</td><td>Email address used to ALWAYS FORCE sending to a fixed email address instead of the shipment recipient's email</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Rule created" %}

```json
{
    "result": "OK",
    "id_regola": X,
    "code": 200
}
```

{% endtab %}

{% tab title="400: Bad Request Rule not created due to a data error" %}

```json
{
    "error": "This rule is already included within another one (X). Try PUT instead",
    "code": 400
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

{% endtab %}
{% endtabs %}

## Edit an existing rule

<mark style="color:orange;">`PUT`</mark> `https://api.gsped.it/[INSTANCE]/transactionalEmail/[ID]`

#### Path Parameters

| Name                                 | Type   | Description            |
| ------------------------------------ | ------ | ---------------------- |
| ID<mark style="color:red;">\*</mark> | String | ID of the rule to edit |

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

#### Request Body

<table><thead><tr><th>Name</th><th width="202">Type</th><th>Description</th></tr></thead><tbody><tr><td>client_id<mark style="color:red;">*</mark></td><td>Numeric</td><td>The client_id the rule applies to</td></tr><tr><td>config<mark style="color:red;">*</mark></td><td>Object</td><td>The configuration container for this client_id (the following parameters must be part of this key)</td></tr><tr><td>sender_commercial_name</td><td>String</td><td><p>Associated template key:</p><pre><code>[sender_commercial_name]
</code></pre><p><strong>Trade name</strong> (optional) <strong>to enter</strong>, displayed before the logo</p><pre><code>[client_logo]
</code></pre><p>in the email template.</p></td></tr><tr><td>order_type_reference<mark style="color:red;">*</mark></td><td><p><strong><code>NotBlank</code></strong><br></p><p><strong><code>Choice</code></strong><code>([</code><br></p><p><code>'ddt_num',</code><br></p><p><code>'ddt_alpha'</code><br></p><p><code>])</code></p></td><td><p>Associated template keys:</p><pre><code>[ddt_alpha][ddt_num]
</code></pre><p>REQUIRED</p><p><strong>Order reference type</strong> (mandatory choice) to enter, displayed with the shipment status text in the email template.</p></td></tr><tr><td>dominio_validato</td><td>bool</td><td>REQUIRED only for the <em>gsped</em> engine<br>Indicates whether the domain has its DNS records configured according to Gsped's instructions for setting up a custom sender email. If <strong>false</strong>, emails are sent from noreply@gsped.com; if <strong>true</strong>, you can customise the <em>from</em> field.</td></tr><tr><td>motore<mark style="color:red;">*</mark></td><td>String</td><td>Email sending engine<br>Possible values:<br>- <em>gsped</em><br>- <em>mailchimp</em></td></tr><tr><td>logo</td><td>String</td><td>REQUIRED only for the <em>gsped</em> engine<br>Base64 of a png image of max 300x300px to be used in the templates</td></tr><tr><td>from<mark style="color:red;">*</mark></td><td>String</td><td>Email address shown as the sender of the transactional email</td></tr><tr><td>cc</td><td>String</td><td>Optional email address in copy</td></tr><tr><td>bcc</td><td>String</td><td>Optional email address in blind copy</td></tr><tr><td>descrizione<mark style="color:red;">*</mark></td><td>String</td><td>Description of the rule and what it does</td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>String</td><td>Email subject</td></tr><tr><td>apikey</td><td>String</td><td>REQUIRED only for the <em>mailchimp</em> engine<br>The API key for the connection with mailchimp</td></tr><tr><td>corrieri<mark style="color:red;">*</mark></td><td>Array</td><td>List of <a href="/gsped-api-english-version/overview/corrieri-e-servizi.md">courier codes</a> this rule applies to.</td></tr><tr><td>statuses<mark style="color:red;">*</mark></td><td>Array</td><td>List of <a href="/gsped-api-english-version/overview/codici-gsped.md#shipment-status-codes">status codes</a> this rule applies to.</td></tr><tr><td>template_slug</td><td>Object</td><td>REQUIRED only for the mailchimp engine.<br>Key=>value object mapping recipient_country=>template_slug among those created in mailchimp.<br>You can use the <strong>*</strong> character as the country to indicate the "rest of the world", i.e. to use the associated template if no matching country is found among those configured.</td></tr><tr><td>to</td><td>String</td><td>Email address used to ALWAYS FORCE sending to a fixed email address instead of the shipment recipient's email</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Rule edited" %}

```json
{
    "result": "OK",
    "id_regola": X,
    "code": 200
}
```

{% endtab %}

{% tab title="400: Bad Request Rule not edited due to a data error" %}

```json
{
    "error": "The current user is not the owner of this rule",
    "code": 400
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

{% endtab %}
{% endtabs %}

## Delete the rule specified by \[ID]

<mark style="color:red;">`DELETE`</mark> `https://api.gsped.it/[INSTANCE]/transactionalEmail/[ID]`

#### Path Parameters

| Name                                 | Type    | Description              |
| ------------------------------------ | ------- | ------------------------ |
| ID<mark style="color:red;">\*</mark> | Numeric | ID of the rule to delete |

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

{% tabs %}
{% tab title="200: OK Rule deleted" %}

```json
{
    "result": true,
    "code": 200
}
```

{% endtab %}

{% tab title="404: Not Found Rule not found" %}

```json
{
    "error": "No rules found for id X",
    "code": 404
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

{% endtab %}
{% endtabs %}