# Maileroo

> Konfiguruje a integruje Maileroo pro odesílání e-mailů přes SMTP relay, Email API nebo oficiální SDK (Node.js, PHP, Python, Go, .NET, Java, Laravel). Použij při nastavování Maileroo, SMTP, Email API, sending keys, SDK integraci, transakčních e-mailech nebo troubleshootingu doručování.

- Skill: `ddanielrrakowski/maileroo` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ddanielrrakowski/maileroo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ddanielrrakowski/maileroo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ddanielrrakowski (https://skillmd.com/u/ddanielrrakowski)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ddanielrrakowski/maileroo

---


# Maileroo

Skill pro práci s [Maileroo](https://maileroo.com/docs/introduction) – SMTP relay, Email API, sending keys a oficiální SDK.

## Kdy použít

Použij při:

- konfiguraci nebo změně odesílání e-mailů přes Maileroo (SMTP, API nebo SDK)
- integraci pomocí oficiálního SDK (Node.js, PHP, Python, Go, .NET, Java, Laravel)
- dotazech na sending keys, API klíče nebo SMTP credentials
- integraci transakčních e-mailů (potvrzení objednávek, notifikace)
- řešení problémů s doručováním nebo chybějící konfigurací

Trigger výrazy: Maileroo, SMTP Maileroo, Email API Maileroo, Maileroo SDK, sending key, odesílání e-mailů, transakční e-maily, konfigurace SMTP, maileroo-sdk.

## SMTP Relay

- **Host:** `smtp.maileroo.com`
- **Porty:** 465 (SSL), 587 (STARTTLS), 2525
- **Autentizace:** povinná (uživatel + heslo)
- **Max velikost zprávy:** 24 MB

### Env proměnné

| Proměnná                 | Popis                                                       |
| ------------------------ | ----------------------------------------------------------- |
| `MAILEROO_SMTP_HOST`     | Host SMTP serveru (typicky `smtp.maileroo.com`)             |
| `MAILEROO_SMTP_PORT`     | Port (465, 587 nebo 2525)                                   |
| `MAILEROO_SMTP_USER`     | SMTP uživatel (obvykle e-mail ověřené domény)               |
| `MAILEROO_SMTP_PASSWORD` | SMTP heslo                                                  |
| `MAILEROO_FROM`          | Adresa odesílatele (From), měla by odpovídat ověřené doméně |

### Příklad (nodemailer)

V projektu je SMTP nastavení v `server/utils/email.ts` – transporter se vytváří z env a používá se pro odeslání (např. `sendOrderConfirmationEmail`). Referenční env viz `.env.example`.

```ts
// Zjednodušeně podle server/utils/email.ts
const transporter = nodemailer.createTransport({
  host: process.env.MAILEROO_SMTP_HOST,
  port: parseInt(process.env.MAILEROO_SMTP_PORT!, 10),
  secure: port === 465,
  requireTLS: port === 587,
  auth: {
    user: process.env.MAILEROO_SMTP_USER,
    pass: process.env.MAILEROO_SMTP_PASSWORD,
  },
});
await transporter.sendMail({ from, to, subject, html });
```

## Email API

- **Base URL:** `https://smtp.maileroo.com/api/v2`
- **Autentizace:** sending key (API key) v hlavičce

### Autentizace

Sending key lze poslat jedním z:

- `Authorization: Bearer YOUR_SENDING_KEY`
- `X-Api-Key: YOUR_SENDING_KEY`

### Odeslání e-mailu

**POST** `/emails`  
Content-Type: `application/json`

Povinná pole:

| Pole                | Typ            | Popis                                                                     |
| ------------------- | -------------- | ------------------------------------------------------------------------- |
| `from`              | object         | `{ "address": "od@domena.cz", "display_name": "Jméno" }` – ověřená doména |
| `to`                | array / object | Příjemci – EmailObject nebo pole EmailObject                              |
| `subject`           | string         | Předmět (max 255 znaků)                                                   |
| `html` nebo `plain` | string         | Tělo zprávy; alespoň jedno je povinné                                     |

Volitelná pole: `cc`, `bcc`, `reply_to`, `tracking`, `tags`, `headers`, `attachments`, `scheduled_at`, `reference_id`. Detail v [reference.md](reference.md).

Příklad těla:

```json
{
  "from": { "address": "info@example.com", "display_name": "Example" },
  "to": [{ "address": "recipient@example.com" }],
  "subject": "Potvrzení objednávky",
  "html": "<p>Děkujeme za objednávku.</p>"
}
```

## Sending keys (API keys)

- **Kde vytvořit:** Maileroo dashboard → Domains → vybrat doménu → v levém menu **Sending Keys** → vytvořit nový klíč.
- **Použití:** Pouze pro **Email API** (REST) a **SDK**. Pro SMTP se používají SMTP credentials (uživatel/heslo), ne sending key.
- V hlavičce requestu: `Authorization: Bearer <sending_key>` nebo `X-Api-Key: <sending_key>`.

## Oficiální SDK

Maileroo nabízí oficiální SDK pro více jazyků. Všechny používají **sending key** (API key), ne SMTP credentials. Přehled a detaily v [reference.md](reference.md#sdk).

| Jazyk / platforma | Instalace / zdroj                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| **Node.js**       | `npm i maileroo-sdk`                                                                             |
| **PHP**           | `composer require maileroo/maileroo-php-sdk`                                                     |
| **Laravel**       | Laravel SDK (viz docs)                                                                           |
| **Python**        | [maileroo-python-sdk](https://github.com/maileroo/maileroo-python-sdk)                           |
| **Go**            | [maileroo-go-sdk](https://github.com/maileroo/maileroo-go-sdk)                                   |
| **.NET (C#)**     | Oficiální SDK – viz [Libraries and SDKs](https://maileroo.com/docs/email-api/libraries-and-sdks) |
| **Java**          | Oficiální SDK – viz [Libraries and SDKs](https://maileroo.com/docs/email-api/libraries-and-sdks) |

### Node.js (maileroo-sdk)

```bash
npm i maileroo-sdk
```

```ts
import { MailerooClient, EmailAddress } from "maileroo-sdk";

const client = new MailerooClient(process.env.MAILEROO_SENDING_KEY!);

const referenceId = await client.sendBasicEmail({
  from: new EmailAddress("info@example.com", "Sender Name"),
  to: [new EmailAddress("recipient@example.com", "Recipient")],
  subject: "Potvrzení",
  html: "<p>Obsah</p>",
  plain: "Obsah",
});
```

SDK dále nabízí: `sendTemplatedEmail`, `sendBulkEmails`, `getScheduledEmails`, `deleteScheduledEmail`, přílohy (`Attachment.fromFile`, `Attachment.fromContent`). Viz [reference.md](reference.md#sdk) a [npm](https://www.npmjs.com/package/maileroo-sdk).

### PHP

```bash
composer require maileroo/maileroo-php-sdk
```

```php
use Maileroo\MailerooClient;
use Maileroo\EmailAddress;

$client = new MailerooClient('your-api-key');
$referenceId = $client->sendBasicEmail([
    'from' => new EmailAddress('sender@example.com', 'Sender Name'),
    'to' => [new EmailAddress('recipient@example.com', 'Recipient')],
    'subject' => 'Hello from Maileroo!',
    'html' => '<h1>Hello</h1>',
    'plain' => 'Hello',
]);
```

Ostatní jazyky: instalace a příklady v [Libraries and SDKs](https://maileroo.com/docs/email-api/libraries-and-sdks) a na GitHubu (`github.com/maileroo/maileroo-*-sdk`).

## Odkazy

- [Maileroo Docs – Introduction](https://maileroo.com/docs/introduction)
- [SMTP Relay – Server Configuration](https://maileroo.com/docs/smtp-relay/server-configuration)
- [Email API – Introduction](https://maileroo.com/docs/email-api/introduction)
- [Libraries and SDKs](https://maileroo.com/docs/email-api/libraries-and-sdks) (všechna oficiální SDK)
- [Send Basic Email](https://maileroo.com/docs/email-api/send-basic-email/) (příklady requestů)
- V projektu: `server/utils/email.ts` (SMTP), `.env.example` (env proměnné)
- Rozšířené detaily API a SDK (response kódy, rate limit, Node.js API, ostatní jazyky): [reference.md](reference.md)