> 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/mail-transazionali/transactionalemail.md).

# TransactionalEmail

Endpoint per configurazione delle email transazionali

{% hint style="danger" %}
Questo endpoint necessita di una specifica voce contrattuale\
Verificare commercialmente se sia possibile utilizzarlo.
{% endhint %}

Questo endpoint permette di configurarsi in autonomia le mail transazionali (mail inviate al cambio di stato di una spedizione).

Le regole sono legate all'utente che effettua la chiamata e sono configurabili per i client\_id ( o invoiced\_client\_id) che il proprio utente può gestire.\
In caso due regole per stesso client\_id si sovrappongano su stesso corriere e stesso stato verrà restituito un errore sulla seconda regola che viene inserita.

La tipologia di invio può avvenire tramite motore *mailchimp* o *gsped* (verificare con Gsped quali siano le differenze e come recuperare eventuali parametri per la configurazione).

## Recupera la singola regola o tutte le regole se non viene specificato nessun \[ID]

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

Per la descrizione dei campi di risposta fare riferimento al metodo POST

#### Path Parameters

| Name | Type    | Description                           |
| ---- | ------- | ------------------------------------- |
| ID   | Numeric | ID della singola regola da recuperare |

#### Headers

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

{% tabs %}
{% tab title="200: OK Regole recuperate" %}

```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 Regola non trovata" %}

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

{% endtab %}

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

{% endtab %}
{% endtabs %}

## Crea una nuova regola

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

#### Headers

| Name                                        | Type   | Description             |
| ------------------------------------------- | ------ | ----------------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY fornita da 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>Il client_id su cui lavora la regola</td></tr><tr><td>config<mark style="color:red;">*</mark></td><td>Object</td><td>Il contenitore della configurazione per questo client_id (i parametri seguenti devono far parte di questa chiave)</td></tr><tr><td>sender_commercial_name</td><td>String</td><td><p>Chiave del template associata:</p><pre><code>[sender_commercial_name]
</code></pre><p><strong>Nome commerciale</strong> (opzionale) <strong>da inserire</strong>, che verrà visualizzato prima del logo</p><pre><code>[client_logo]
</code></pre><p>nel template dell’email.</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>Chiavi del template associate:</p><pre><code>[ddt_alpha][ddt_num]
</code></pre><p>REQUIRED</p><p><strong>Tipo di riferimento dell’ordine</strong> (di scelta obbligatoria) da inserire, che verrà visualizzato con il testo dello status della spedizione nel template dell’email.</p></td></tr><tr><td>dominio_validato</td><td>bool</td><td>REQUIRED solamente per motore <em>gsped</em><br>Indica se il dominio ha i campi DNS configurati secondo indicazioni di Gsped per setting della email mittente personalizzata. Se <strong>false</strong> le email verranno inviate da noreply@gsped.com, se <strong>true</strong> si potrà personalizzare il campo <em>from</em>.</td></tr><tr><td>motore<mark style="color:red;">*</mark></td><td>String</td><td>Motore invio email<br>Possibili valori:<br>- <em>gsped</em><br>- <em>mailchimp</em></td></tr><tr><td>logo</td><td>String</td><td>REQUIRED solamente per motore <em>gsped</em><br>Base64 di una immagine png di max 300x300px da utilizzare nei template</td></tr><tr><td>from<mark style="color:red;">*</mark></td><td>String</td><td>Indirizzo email che comparirà come mittente della mail transazionale</td></tr><tr><td>cc</td><td>String</td><td>Indirizzo email eventualmente in copia</td></tr><tr><td>bcc</td><td>String</td><td>Indirizzo email eventualmente in copia nascosta</td></tr><tr><td>descrizione<mark style="color:red;">*</mark></td><td>String</td><td>Descrizione della regola e di cosa fa</td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>String</td><td>Oggetto della mail</td></tr><tr><td>apikey</td><td>String</td><td>REQUIRED solamente per motore <em>mailchimp</em><br>L'apikey per il collegamento con mailchimp</td></tr><tr><td>corrieri<mark style="color:red;">*</mark></td><td>Array</td><td>Lista dei <a href="https://apidocs.gsped.com/overview/corrieri-e-servizi.md">codici corriere</a> su cui vale questa regola.</td></tr><tr><td>statuses<mark style="color:red;">*</mark></td><td>Array</td><td>Lista dei <a href="https://apidocs.gsped.com/overview/codici-gsped.md#codici-status-spedizione">codici stato</a> su cui vale questa regola.</td></tr><tr><td>template_slug</td><td>Object</td><td>REQUIRED solamente per motore mailchimp.<br>Oggetto chiave=>valore di abbinamento nazione_destinatario=>template_slug tra quelli creati da mailchimp.<br>C'è la possibilità di utilizzare come nazione il carattere <strong>*</strong> per indicare il "resto del mondo" ossia di utilizzare il template abbinato se non si trova la nazione adatta tra quelle configurate.</td></tr><tr><td>to</td><td>String</td><td>Indirizzo email per FORZARE sempre ad un indirizzo email fisso e non alla mail del destinatario della spedizione</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Regola creata" %}

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

{% endtab %}

{% tab title="400: Bad Request Regola non creata per errore nei dati" %}

```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 %}

## Modifica una regola esistente

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

#### Path Parameters

| Name                                 | Type   | Description                   |
| ------------------------------------ | ------ | ----------------------------- |
| ID<mark style="color:red;">\*</mark> | String | ID della regola da modificare |

#### Headers

| Name                                        | Type   | Description             |
| ------------------------------------------- | ------ | ----------------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY fornita da 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>Il client_id su cui lavora la regola</td></tr><tr><td>config<mark style="color:red;">*</mark></td><td>Object</td><td>Il contenitore della configurazione per questo client_id (i parametri seguenti devono far parte di questa chiave)</td></tr><tr><td>sender_commercial_name</td><td>String</td><td><p>Chiave del template associata:</p><pre><code>[sender_commercial_name]
</code></pre><p><strong>Nome commerciale</strong> (opzionale) <strong>da inserire</strong>, che verrà visualizzato prima del logo</p><pre><code>[client_logo]
</code></pre><p>nel template dell’email.</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>Chiavi del template associate:</p><pre><code>[ddt_alpha][ddt_num]
</code></pre><p>REQUIRED</p><p><strong>Tipo di riferimento dell’ordine</strong> (di scelta obbligatoria) da inserire, che verrà visualizzato con il testo dello status della spedizione nel template dell’email.</p></td></tr><tr><td>dominio_validato</td><td>bool</td><td>REQUIRED solamente per motore <em>gsped</em><br>Indica se il dominio ha i campi DNS configurati secondo indicazioni di Gsped per setting della email mittente personalizzata. Se <strong>false</strong> le email verranno inviate da noreply@gsped.com, se <strong>true</strong> si potrà personalizzare il campo <em>from</em>.</td></tr><tr><td>motore<mark style="color:red;">*</mark></td><td>String</td><td>Motore invio email<br>Possibili valori:<br>- <em>gsped</em><br>- <em>mailchimp</em></td></tr><tr><td>logo</td><td>String</td><td>REQUIRED solamente per motore <em>gsped</em><br>Base64 di una immagine png di max 300x300px da utilizzare nei template</td></tr><tr><td>from<mark style="color:red;">*</mark></td><td>String</td><td>Indirizzo email che comparirà come mittente della mail transazionale</td></tr><tr><td>cc</td><td>String</td><td>Indirizzo email eventualmente in copia</td></tr><tr><td>bcc</td><td>String</td><td>Indirizzo email eventualmente in copia nascosta</td></tr><tr><td>descrizione<mark style="color:red;">*</mark></td><td>String</td><td>Descrizione della regola e di cosa fa</td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>String</td><td>Oggetto della mail</td></tr><tr><td>apikey</td><td>String</td><td>REQUIRED solamente per motore <em>mailchimp</em><br>L'apikey per il collegamento con mailchimp</td></tr><tr><td>corrieri<mark style="color:red;">*</mark></td><td>Array</td><td>Lista dei <a href="https://apidocs.gsped.com/overview/corrieri-e-servizi.md">codici corriere</a> su cui vale questa regola.</td></tr><tr><td>statuses<mark style="color:red;">*</mark></td><td>Array</td><td>Lista dei <a href="https://apidocs.gsped.com/overview/codici-gsped.md#codici-status-spedizione">codici stato</a> su cui vale questa regola.</td></tr><tr><td>template_slug</td><td>Object</td><td>REQUIRED solamente per motore mailchimp.<br>Oggetto chiave=>valore di abbinamento nazione_destinatario=>template_slug tra quelli creati da mailchimp.<br>C'è la possibilità di utilizzare come nazione il carattere <strong>*</strong> per indicare il "resto del mondo" ossia di utilizzare il template abbinato se non si trova la nazione adatta tra quelle configurate.</td></tr><tr><td>to</td><td>String</td><td>Indirizzo email per FORZARE sempre ad un indirizzo email fisso e non alla mail del destinatario della spedizione</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Regola modificata" %}

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

{% endtab %}

{% tab title="400: Bad Request Regola non modificata per errore nei dati" %}

```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 %}

## Elimina la regola specificata con \[ID]

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

#### Path Parameters

| Name                                 | Type    | Description                  |
| ------------------------------------ | ------- | ---------------------------- |
| ID<mark style="color:red;">\*</mark> | Numeric | ID della regola da eliminare |

#### Headers

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

{% tabs %}
{% tab title="200: OK Regola cancellata" %}

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

{% endtab %}

{% tab title="404: Not Found Regola non trovata" %}

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

{% endtab %}

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

{% endtab %}
{% endtabs %}
