=== TopEmail – transakční e-maily ===
Contributors: topemailcz
Tags: email, smtp, woocommerce, transactional email, deliverability
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Odesílá všechny e-maily WordPressu a WooCommerce přes TopEmail.cz z vaší ověřené domény: REST API nebo SMTP relay, doručenky, záložní odeslání.

== Description ==

**Česky**

Plugin přesměruje veškerou odchozí poštu WordPressu (`wp_mail()`), tedy i všechny e-maily WooCommerce (potvrzení objednávky, změny stavu, faktury z PDF pluginů, reset hesla, kontaktní formuláře), na českou službu pro transakční e-maily [TopEmail.cz](https://topemail.cz). E-maily odcházejí z vaší vlastní domény s DKIM, SPF a DMARC, takže končí v doručené poště, ne ve spamu.

* **Režim API (doporučeno):** každý e-mail jde jedním HTTP požadavkem na `POST https://topemail.cz/api/email/send`. Přílohy (PDF faktury) se posílají jako base64, hlavičky Reply-To, Cc, Bcc a Content-Type se zachovají, vlastní hlavičky `X-*` se předají dál.
* **Režim SMTP:** plugin přenastaví PHPMailer na `smtp.topemail.cz` (port 587 STARTTLS nebo 465 TLS), přihlášení API klíčem. Hodí se na hostingu, který blokuje odchozí HTTP.
* **Značka objednávky:** k e-mailům objednávek se přidá značka `order` = číslo objednávky a `type` = typ e-mailu (např. `customer_completed_order`). Značky vidíte v historii TopEmail a ve webhooku `email.status`, takže doručenku spárujete s objednávkou.
* **Idempotence:** opakované odeslání stejného e-mailu ve stejné minutě (např. při dvojím uložení objednávky) se neposílá dvakrát (`Idempotency-Key`).
* **Záložní odeslání:** když TopEmail vrátí chybu serveru (5xx) nebo se nepodaří spojit, e-mail odejde původní cestou WordPressu. Volitelné.
* **Přehled posledních 10 e-mailů** se stavem doručení (doručeno, odloženo, nedoručitelné, spam) načteným z TopEmail API, tlačítko „Odeslat testovací e-mail“ a ověření API klíče přímo v nastavení.
* **Logování** chyb do WooCommerce > Stav > Protokoly (zdroj `topemail`).
* Funguje i bez WooCommerce (nastavení pak najdete v Nastavení > TopEmail). Kompatibilní s HPOS.

**English**

Routes all WordPress and WooCommerce outgoing e-mail (`wp_mail()`) through TopEmail.cz, a Czech transactional e-mail service, so messages leave from your own verified domain with DKIM/SPF/DMARC. Choose the REST API mode (attachments, Reply-To/Cc/Bcc, order tags, idempotency, optional fallback to the default WordPress mailer on 5xx/network errors) or the SMTP relay mode (smtp.topemail.cz, port 587/465). The settings screen shows the last ten sends with live delivery status, a test e-mail button and an API key check. Works without WooCommerce too (Settings > TopEmail).

**Služba třetí strany**

Plugin používá placenou službu TopEmail.cz (provozovatel Vojtěch Šafář, IČO 03346951, Praha). Při každém odeslání se na `https://topemail.cz/api` přenáší adresy příjemců, předmět, tělo e-mailu, přílohy, hlavičky a značky; v SMTP režimu totéž na `smtp.topemail.cz`. Ověření klíče a načtení stavů přenáší jen API klíč a identifikátory e-mailů. Bez vloženého API klíče plugin nic neodesílá.

* Obchodní podmínky: [https://topemail.cz/obchodni-podminky](https://topemail.cz/obchodni-podminky)
* Zásady ochrany osobních údajů: [https://topemail.cz/zasady-ochrany-osobnich-udaju](https://topemail.cz/zasady-ochrany-osobnich-udaju)
* Zpracovatelská smlouva (GDPR): [https://topemail.cz/zpracovatelska-smlouva](https://topemail.cz/zpracovatelska-smlouva)
* Dokumentace API: [https://topemail.cz/api-integrace](https://topemail.cz/api-integrace)

**Hooky pro vývojáře**

* `topemail_wc_should_send` (filter): vraťte `false` a e-mail pošle WordPress sám; parametry `$send, $atts, $ctx`.
* `topemail_wc_payload` (filter): úprava těla požadavku na API; `$payload, $atts, $ctx`.
* `topemail_wc_tags` (filter): značky k e-mailu; `$tags, $ctx`.
* `topemail_wc_order_id` (filter): id objednávky zjištěné z WooCommerce e-mailu; `$order_id, $email, $params`.
* `topemail_wc_fallback` (filter): zda po chybě API použít záložní odeslání; `$fallback, $error, $transient, $atts, $ctx`.
* `topemail_wc_sent` (action): po přijetí e-mailu službou; `$result, $payload, $atts, $ctx`.

== Installation ==

1. Nainstalujte a aktivujte plugin.
2. Zaregistrujte se na [topemail.cz](https://topemail.cz), přidejte a ověřte doménu (Domény) a vytvořte API klíč (API klíče a SMTP).
3. Otevřete WooCommerce > Nastavení > E-maily > TopEmail (bez WooCommerce Nastavení > TopEmail), vložte API klíč ve formátu `clientId:secret` a klikněte na „Ověřit API klíč“.
4. Vyplňte adresu a jméno odesílatele na ověřené doméně a uložte.
5. Odešlete si testovací e-mail a zkontrolujte stav doručení v přehledu pod nastavením.

== Frequently Asked Questions ==

= Z jaké adresy mohu odesílat? =

Jen z domény, kterou jste v TopEmail ověřili DNS záznamy (DKIM, SPF, DMARC). Freemailové adresy (gmail.com, seznam.cz) nelze použít. Adresa odesílatele v pluginu nahradí odesílatele z WordPressu i WooCommerce.

= Co se stane, když TopEmail nefunguje? =

Při chybě serveru nebo výpadku spojení plugin (pokud je zapnuté záložní odeslání) předá e-mail původnímu mailerů WordPressu. Odmítnuté požadavky (neověřená doména, chybějící kredit, neplatný klíč) se neopakují: najdete je v přehledu posledních e-mailů a v logu WooCommerce.

= Jak se přenášejí přílohy PDF faktur? =

Pluginy pro PDF faktury předávají cestu k souboru do `wp_mail()`. Plugin soubor načte, zakóduje do base64 a pošle v poli `attachments`. Celková velikost zprávy je omezena na 10 MB.

= API nebo SMTP? =

API režim je rychlejší a umí značky objednávky, idempotenci a záložní odeslání. SMTP režim použijte, když hosting blokuje odchozí HTTPS požadavky nebo chcete zachovat stávající nastavení PHPMaileru.

= Kolik to stojí? =

Prvních 1 000 e-mailů měsíčně je zdarma, dále 0,06 Kč za e-mail bez DPH (objemové ceny v [ceníku](https://topemail.cz/cenik)). Plugin je zdarma.

= Kde najdu chyby? =

WooCommerce > Stav > Protokoly, zdroj `topemail`. Bez WooCommerce se chyby zapisují do PHP error logu.

== Changelog ==

= 1.0.0 =
* První vydání: přesměrování wp_mail() přes TopEmail REST API, SMTP režim, přílohy, hlavičky Reply-To/Cc/Bcc, značka objednávky, Idempotency-Key, záložní odeslání přes WordPress, přehled posledních e-mailů se stavem doručení, testovací e-mail, logování do WooCommerce.
