# Přílohy

> Přikládejte k e-mailům z API soubory v base64 nebo z URL, vkládejte obrázky přes Content-ID a dodržte povolené typy souborů a limity velikosti.

Tato stránka ukazuje, jak k e-mailům odesílaným přes `POST /emails` přiložit soubory, buď jako obsah zakódovaný v base64, nebo tak, že je Emailit stáhne z URL. Popisuje také vložené obrázky, povolené typy souborů a limity velikosti.

## Pole přílohy

Předejte pole `attachments`. Každá položka je objekt s těmito poli:

- `filename` (string, povinné): Název souboru, který uvidí příjemce. Musí končit [povolenou příponou](#allowed-file-types).
- `content` (string): Soubor zakódovaný v base64. Použijte buď `content`, nebo `url`, ne obojí.
- `url` (string): URL s `http://` nebo `https://`, ze které Emailit soubor stáhne. Použijte buď `content`, nebo `url`, ne obojí.
- `content_type` (string): Typ MIME, například `application/pdf`. Povinný s `content`. S `url` je výchozí hodnotou `Content-Type`, který vrátí server.
- `content_id` (string): Content-ID. Když ho nastavíte, příloha se stane vloženou a vaše HTML ji může zobrazit přes `cid:`.
- `encoding` (string): Jak je `content` zakódovaný. Ponechte `base64`, pokud nemáte důvod ho měnit.

## Přiložte soubor v base64

Načtěte soubor, zakódujte ho do base64 a odešlete ho s jeho typem MIME.

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme Billing <billing@acme.com>\",
    \"to\": \"ada@example.com\",
    \"subject\": \"Invoice INV-1042\",
    \"text\": \"Your invoice is attached.\",
    \"attachments\": [{
      \"filename\": \"INV-1042.pdf\",
      \"content\": \"$(base64 < INV-1042.pdf | tr -d '\n')\",
      \"content_type\": \"application/pdf\"
    }]
  }"
```

**Node.js**

```javascript
import { readFile } from 'node:fs/promises';
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);
const pdf = await readFile('INV-1042.pdf');

await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: 'ada@example.com',
  subject: 'Invoice INV-1042',
  text: 'Your invoice is attached.',
  attachments: [
    {
      filename: 'INV-1042.pdf',
      content: pdf.toString('base64'),
      content_type: 'application/pdf',
    },
  ],
});
```

**Python**

```python
import base64
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

with open("INV-1042.pdf", "rb") as f:
    pdf = base64.b64encode(f.read()).decode("ascii")

client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": "ada@example.com",
    "subject": "Invoice INV-1042",
    "text": "Your invoice is attached.",
    "attachments": [{
        "filename": "INV-1042.pdf",
        "content": pdf,
        "content_type": "application/pdf",
    }],
})
```

**PHP**

```php
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Invoice INV-1042',
    'text' => 'Your invoice is attached.',
    'attachments' => [[
        'filename' => 'INV-1042.pdf',
        'content' => base64_encode(file_get_contents('INV-1042.pdf')),
        'content_type' => 'application/pdf',
    ]],
]);
```

## Přiložte soubor z URL

Místo toho, abyste soubor kódovali sami, předejte Emailitu `url`. Emailit soubor stáhne při sestavování zprávy, takže požadavek trvá tak dlouho jako stahování.

```json
{
  "from": "Acme Billing <billing@acme.com>",
  "to": "ada@example.com",
  "subject": "Invoice INV-1042",
  "text": "Your invoice is attached.",
  "attachments": [
    {
      "filename": "INV-1042.pdf",
      "url": "https://files.acme.com/invoices/INV-1042.pdf"
    }
  ]
}
```

URL musí splňovat tato pravidla, jinak požadavek selže s `422` a `Attachment error`:

- Používá `http` nebo `https` a vede na veřejný server. Privátní a interní adresy se odmítají.
- Vrací soubor přímo se stavem `2xx`. Přesměrování se nenásledují.
- Stahování skončí do 30 sekund.
- Soubor není větší než 25 MB podle své hlavičky `Content-Length`.

Emailit sestavuje pro každého příjemce samostatnou kopii zprávy a přílohy z URL stahuje pro každou kopii. Zajistěte, aby podepsané nebo časově omezené URL zůstaly platné po celou dobu zpracování požadavku a aby server se soubory zvládl jedno stažení na každého příjemce.

## Vložte obrázky do textu

Pokud chcete obrázek zobrazit přímo v těle HTML, a ne jako samostatnou přílohu, dejte mu `content_id` a odkažte na toto ID přes `cid:` ve značce `img`.

```json
{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "subject": "Your weekly report",
  "html": "<p><img src=\"cid:chart-week-40\" alt=\"Weekly signups\" width=\"600\"></p>",
  "attachments": [
    {
      "filename": "chart.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAA...",
      "content_type": "image/png",
      "content_id": "chart-week-40"
    }
  ]
}
```

`content_id` v příloze a hodnota za `cid:` se musí přesně shodovat. Vložené obrázky zvětšují zprávu pro každého příjemce, takže pro loga a další sdílené obrázky je obvykle lepší volbou URL hostovaného obrázku v HTML.

## Limity velikosti

| Limit | Hodnota |
| --- | --- |
| Celá zpráva po zakódování | 40 MB. Větší zprávy selžou s `413 Message too large`. |
| Jedna příloha stažená z `url` | 25 MB |
| Časový limit stahování z `url` | 30 sekund |
| Tělo požadavku JSON | 50 MB |

Kódování base64 zvětší soubory přibližně o třetinu a limit 40 MB platí pro zakódovanou zprávu. V praxi udržujte celkovou velikost souborů pod přibližně 29 MB. Cokoli většího nahrajte do vlastního úložiště a pošlete odkaz.

## Povolené typy souborů

`filename` musí končit jednou z těchto přípon. Jakákoli jiná přípona nebo název bez přípony neprojde validací a požadavek vrátí `400`.

| Kategorie | Přípony |
| --- | --- |
| Text | `.txt`, `.csv`, `.log`, `.css`, `.ics`, `.xml` |
| Obrázky | `.jpg`, `.jpe`, `.jpeg`, `.gif`, `.png`, `.bmp`, `.psd`, `.tif`, `.tiff`, `.svg`, `.indd`, `.ai`, `.eps` |
| Dokumenty | `.doc`, `.docx`, `.rtf`, `.odt`, `.ott`, `.pdf`, `.pub`, `.pages`, `.mobi`, `.epub` |
| Zvuk | `.mp3`, `.m4a`, `.m4v`, `.wma`, `.ogg`, `.flac`, `.wav`, `.aif`, `.aifc`, `.aiff` |
| Video | `.mp4`, `.mov`, `.avi`, `.mkv`, `.mpeg`, `.mpg`, `.wmv` |
| Tabulky | `.xls`, `.xlsx`, `.ods`, `.numbers` |
| Prezentace | `.odp`, `.ppt`, `.pptx`, `.pps`, `.key` |
| Archivy a kontakty | `.zip`, `.vcf` |
| E-mail | `.eml` |
| Podpisy a šifrování | `.p7c`, `.p7m`, `.p7s`, `.pgp`, `.asc`, `.sig` |

Spustitelné soubory a skripty na seznamu nejsou a přiložit je nelze.

## Načtěte přílohy odeslaného e-mailu

[Výpis příloh](/cs/docs/api-reference/emails/attachments/) (`GET /emails/{id}/attachments`) vrací každou přílohu s poli `filename`, `content_type`, `size`, `content_id`, `content_disposition` (`attachment`, nebo `inline`) a `content` v base64. Potřebuje klíč s oprávněním **Full Access**. Přílohy se smažou spolu s obsahem zprávy, když skončí doba [uchovávání dat](/cs/docs/data-retention/).

## Řešení problémů

| Chyba | Co zkontrolovat |
| --- | --- |
| `Attachment at index 0 missing content_type (required when using 'content')` | Přidejte `content_type` ke každé příloze v base64. |
| `Attachment 'report.exe' has unsupported file type '.exe'` | Použijte povolenou příponu, nebo soubor vložte do `.zip`. |
| `Attachment at index 0 cannot have both 'content' and 'url'` | Odešlete jen jedno z nich. |
| `Attachment error` s `Failed to fetch attachment` | URL vrátila chybový stav, přesměrovala, vypršel časový limit, nebo není veřejná. Pro kontrolu ji otevřete ze serveru mimo vaši síť. |
| `Attachment error` s `Attachment too large (max 25MB)` | Soubor hostujte a místo něj pošlete odkaz. |
| `413 Message too large` | Zmenšete celkovou velikost příloh. |

## Související

- [Odeslání e-mailu](/cs/docs/email-api/send-email/)
- [Odeslání e-mailu](/cs/docs/api-reference/emails/send/) v referenci API
- [Uchovávání dat](/cs/docs/data-retention/)

---
Zdroj: https://emailit.com/cs/docs/email-api/attachments/