---
tags: DOG
---
# **DOG Mailer API** `v1.2.0`
> API slouží pro odesílání emailů pomocí služby SendGrid. Implementuje pouze metodu mail/send. Umí zajistit základní mailové vlastnosti jako plain/html, přiložení příloh a nebo využití Dynamic Templates ze SendGridu.

---
## **Změny ve verzích**
### **v1.2.0**
#### **Přidáno**
* Přidání podpory pro načítání dokumentů z DMS

### **v1.1.0**
#### **Přidáno**
* Přidání podpory pro dynamic templates

### **v1.0.0**
* Zaváděcí verze

---
### **Umístění API**
#### **TEST** prostředí
* Lokální síť: https://dog.test.ux.bee.corp/api/v1
* Externí zóna: https://apitest.bohemiaenergy.cz/dog
#### **PROD** prostředí
* Lokální síť: https://dog.bee.corp/api/v1
* Externí zóna: https://api.bohemiaenergy.cz/dog

### **Ověření přístupu k API**
Ověření je řešeno pomocí `API-KEY` vloženého do hlavičky
* `Authorization: Bearer <API-KEY>`

V případě použití přístupu z externí zóny, je nutné ještě navíc přístupový `PROXY-KEY` pro `Proxy` umístěný do hlavičky
* `X-APP-KEY: <PROXY-KEY>`

### **Vysvětlivky**
* ==*== - označuje povinné položky
* [color=#ff4500] - další informace na konci dokumentu v Příloze

## **Způsob zpracování chyb**

#### **V případě jakékoliv chyby je vráceno například:**

{
    "intID": "b59fb26d-89df-4fea-9560-0dc3379eda82",
    "response": {
        "error": {
            "code": "MISSING_MANDATORY_DATA",
            "message": "Missing mandatory nodes: entity",
            "data": {}
        }
    }
}

#### **Popis:**
* **intID** `string` - interní ID DOG, pod kterým je provedeno zalogování požadavku
* **response** `object` - objekt s tělem odpovědi
* **error** `object` - objekt s tělem chyby
* **code** `string` - označení chyby, strojově zpracovatelný kód
* **message** `string` - doplňující popis chyby, většinou předávaná hodnota z dalších systémů nebo lidksy čitelná podoba chyby
* **data** `object` - další strojově zpracovatelné detaily chyby

### **Seznam kódů**

| Code | Message | Data | Popis |
| --------------------------- | -------------------------------------- |:----:| ----- |
| `INVALID_INPUT_JSON` | Chyba z parseru | - | Vstupní data nejsou validní JSON formát |
| `MISSING_MANDATORY_DATA` | List chybějících polí vstupních dat | - | Kontrola vstupních dat, kontrola povinných položek a jejich struktury, případně validita stupních dat |
| `SENDGRID_INTERNAL_ERROR` | | - | Vnitřní chyba zpracování odpovědi od Sendgridu |
| `DMS_INTERNAL_ERROR` | Přeposlaná chyba z DMS | - | Vnitřní chyna na strane DMS |
| `DOG_MAILER_INTERNAL_ERROR` | | - | Vnitřní chyba DOG Mailer |

**Způsob reportování chyb je u všech endpointů stejný. Dále nebude popisovaný.**

---
## **dog://mail/send**
> Odeslání emailu pomocí služby SendGrid

**Metoda:** `POST` \
**URL:** `/mail/send` \
**Tělo dotazu:** `application/json` \
**Tělo odpovědi:** `application/json`

#### **Příklad:**

{
    "from": {
        "email": "[e-mail]",
        "name": "BOHEMIA ENERGY"
    },
    "to": [
        {
            "email": "[e-mail]",
            "name": "Václav Hořejší"
        }
    ],
    "cc": [],
    "bcc": [],
    "subject": "test email",
    "body": {
        "plain": "plain body",
        "html": "<b>html</b> body",
        "template": {
            "id": "d-fd6d82e03d114a73986720ba50428da4",
            "data": {
                "user": {
                    "firstname": "Václav",
                    "surname": "Hořejší"
                }
            }
        }
    },
    "attachments": [
        {
            "dms": {
                "id": 123456,
                "version": 4
            },
            "name": "sou.pdf",
            "cid": "xxxx",
            "data": "data:application/pdf;base64,JVBERi0xLjcKJeLjz9MKMjIgMCBvY..."
        }
    ]
}

#### **Popis:**
* **from** ==*== `object` - objekt s informací o odesílateli (FROM)
* **email** ==*== `string` - adresa odesílatele
* **name** `string` - jméno odesílatele
* **to** ==*== `array of objects` - pole objektů adresátů, má stejnou strukturu jako `from`. **Pozor, musí to být pole a musí obsahovat aspoň jeden objekt s `email`**
* **cc** `array of objects` - pole objektů adresátů v kopii. Funguje stejně jako `to`
* **bcc** `array of objects` - pole objektů skrytých adresátů v kopii. Funguje stejně jako `to`
* **subject** `string` - předmět emailu (==*== pokud není použitý `body.template`)
* **body** `object` - objekt definující tělo emailu
* **plain** `string` - plaintextová verze těla emailu (==*== pokud není použito `body.html` nebo `body.template`)
* **html** `string` - html verze těla emailu (==*== pokud není použito `body.plain` nebo `body.template`)
* **template** `object` - objekt pro použití Dynamic Templates ze SendGridu. Pokud je použito, tak má vyšší prioritu než `body.plain` a `body.html`.
* **id** `string` - identifikátor šablony z Dynamic Templates v SendGridu. Je vygenerován při založení šablony v Sendgridu.
* **data** `object` - objekt odpovídající struktuře elementů v Dynamic Templates. Do šablony se zapisují jako `{{name}}` nebo `{{user.firstname}}`. Detailní dokumentace pro tvorbu Dynamic Templates je: https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/
* **attachments** `array of objects` - pole objektů s přílohami
* **dms** `object` - objekt s odkazem na DMS
* **id** `int` - ID souboru v DMS
* **version** `int` [*1*] - verze souboru v DMS
* **name** `string` - název souboru, bude použito pro pojmenování souboru v příloze
* **cid** `string` - název souboru pro použití inline vložení do těla emailu pomocí `<img src="cid:xxxx">`
* **data** `string` - data mimetype base64 soubor

#### **Poznámky:**
V případě, že je použito `attachments[].dms` je nutné u správce DMS zajistit práva na daný typ souborů pro DOG

#### **Odpověď v případě úspěšného odeslání emailu:**

{
    "intID": "0120f618-7d12-471b-aa22-151d21976173",
    "response": {
        "code": 202,
        "mailToken": "mzPllLfaTLe3OLs42FkcnA"
    }
}

#### **Popis:**
* **intID** `string` - interní ID DOG, pod kterým je provedeno zalogování požadavku
* **response** `object` - objekt s tělem odpovědi
* **code** `int` - kód výsledku zpracování požadavku Sendgridem. Popis kódů: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html
* **mailToken** `string` - unikátní identifikátor emailu v rámci Sendgrid

#### **Odpověď v připadě chyby při odeslání emailu:**

{
    "intID": "8a226223-26ad-44e9-ba85-bdd6b81a4de2",
    "response": {
        "code": 400,
        "errors": [
            {
                "field": "from.email",
                "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.from",
                "message": "The from email does not contain a valid address."
            }
        ]
    }
}

#### **Popis:**
* **intID** `string` - interní ID DOG, pod kterým je provedeno zalogování požadavku
* **response** `object` - objekt s tělem odpovědi
* **code** `int` - kód výsledku zpracování požadavku Sendgridem. Popis kódů: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html
* **errors** `array of objects` - pole objektů s popisem všech chyb v rámci volání
* **field** `string` - pole, kterého se problém týká
* **help** `string` - odkaz do dokumentace Sendgridu k danému problému
* **message** `string` - rychlý popis chyby

---
## Přílohy
### Číselník DOG.dog.entity[]

}
  "entity": {
    "BE": ["BE", "71", "B", "BEE", "bohemiaenergy.cz"],
    "CE": ["CE", "82", "C", "comfortenergy.cz"],
    "XE": ["XE", "81", "X", "X Energie", "xenergie.cz"],
    "3E": ["3E", "100", "E", "3-e.cz"],
    "BD": ["BD", "63", "Z", "BEZ", "bezdodavatele.cz"],
    "SE": ["SE", "72", "S", "SK", "SKE", "slovakiaenergy.sk"],
    "AM": ["AM", "75", "A", "ampermarket.cz"],
    "BPL": ["BPL", "beplan.cz"],
    "ECS": ["ECS", "77", "P", "energie-cs.cz"]
  }
}