[Intum](https://intum.fr/aide.md) / [Mail](https://intum.fr/aide/mail.md)

# [E-maile](https://intum.fr/aide/mail/e-maile.md) | [API](#api)

## Czym są e-maile w Intum?

Moduł Mail to **współdzielona skrzynka pocztowa dla całej firmy**. Pozwala zapanować nad pocztą firmową — zamiast osobnych skrzynek, które zna tylko ich właściciel, e-maile trafiają do wspólnego systemu gdzie cały zespół widzi co przychodzi, kto nad czym pracuje i co wymaga uwagi.

Dzięki temu:

- Żaden e-mail od klienta **nie zostanie przeoczony** — nawet gdy ktoś jest na urlopie
- Widać **kto za co odpowiada** — przydzielone wiadomości mają jasnego właściciela
- **Historia korespondencji** jest dostępna dla całego zespołu — nie w prywatnej skrzynce jednej osoby
- E-maile są powiązane z [zadaniami](../organizacja/zadania), kontaktami CRM i [folderami](foldery)

## Odbieranie i wysyłanie

E-maile trafiają do systemu przez [skrzynki pocztowe](skrzynki-e-mail) (przekierowanie SMTP). Wysyłanie odbywa się przez skonfigurowany serwer SMTP skrzynki.

### Statusy wysyłki

- **Odebrane** — wiadomość przyszła z zewnątrz
- **Wysłane** — wiadomość wysłana z systemu
- **Szkic** — zapisany, niewysłany e-mail
- **Zaplanowane** — e-mail z ustawioną datą wysyłki w przyszłości

## Wątki

E-maile są automatycznie grupowane w wątki na podstawie nagłówków SMTP (References, In-Reply-To). Odpowiedź na e-mail trafia do tego samego wątku — cała historia rozmowy jest w jednym miejscu.

## Współdzielone e-maile i przydzielanie

Przychodzące wiadomości nie trafiają do jednej osoby — są widoczne dla całego zespołu i czekają na przydzielenie. To kluczowa różnica w stosunku do klasycznej poczty.

### Jak działa przydzielanie

Każdy e-mail ma pole **Osoba odpowiedzialna**, które określa kto zajmuje się daną wiadomością. E-mail można przydzielić do:

- **[Użytkownika](../organizacja/uzytkownik)** — konkretna osoba odpowiedzialna za obsługę
- **[Grupy](../organizacja/grupa)** — zespół osób współdzielących odpowiedzialność (np. "Obsługa klienta", "Sprzedaż"). Każdy członek grupy widzi e-mail i może na niego odpowiedzieć
- **[Zespołu](../organizacja/zespol)** — przypisanie do całego zespołu

### Widoki skrzynki

- **Do przydzielenia** — e-maile bez przypisanego odpowiedzialnego. To główna kolejka wymagająca uwagi
- **Moje** — e-maile przydzielone do bieżącego użytkownika
- **Wszystkie** — pełna lista e-maili
- **Wysłane** — wiadomości wysłane z systemu
- **Kosz** — usunięte wiadomości
- **Spam** — wiadomości oznaczone jako spam
- **Odłożone** — wątki odłożone na później (snooze)

### Automatyczne przydzielanie

E-maile mogą być automatycznie przydzielane przez:

- **[Filtry](filtry)** — reguły przypisujące odpowiedzialnego na podstawie nadawcy, domeny lub tematu
- **[Skrzynkę](skrzynki-e-mail)** — domyślny odpowiedzialny ustawiony na skrzynce pocztowej
- **Kontakt CRM** — jeśli nadawca jest rozpoznany, e-mail może odziedziczyć odpowiedzialnego z kontaktu

### Zmiana odpowiedzialnego

Odpowiedzialnego można zmienić:

- Z poziomu widoku e-maila — kliknij na pole odpowiedzialnego
- Operacjami zbiorczymi — zaznacz wiele e-maili i zmień przypisanie
- Przez API — pole `responsible_id` i `responsible_type`

## Pola e-maila

- **Temat** — temat wiadomości
- **Od** — nadawca
- **Do** — odbiorca
- **Dw / Udw** — kopia / ukryta kopia
- **Treść** — treść wiadomości (HTML)
- **[Skrzynka](skrzynki-e-mail)** — z której skrzynki wysłany
- **[Folder](foldery)** — przypisany folder
- **Osoba odpowiedzialna** — [użytkownik](../organizacja/uzytkownik), [grupa](../organizacja/grupa) lub [zespół](../organizacja/zespol)
- **Status** — [status](../organizacja/statusy) obsługi e-maila
- **Priorytet** — ważność (1-5)
- **Kontakt** — powiązany kontakt z CRM
- **[Tagi](../organizacja/tagi)** — etykiety kategoryzujące

## Załączniki

Do e-maila można dodawać pliki. Załączniki odebrane z zewnątrz są przechowywane w chmurze z bezpiecznym dostępem przez signed URL.

## Powiązania

- **[Zadania](../organizacja/zadania)** — e-mail można powiązać z zadaniami (i odwrotnie)
- **Kontakt CRM** — automatyczne przypisanie na podstawie adresu nadawcy
- **Formularze** — e-mail może być wynikiem przesłania formularza

## Operacje

- **Archiwizacja** — ukrycie e-maila z widoku skrzynki odbiorczej
- **Kosz** — przeniesienie do kosza (soft delete)
- **Spam** — oznaczenie jako spam
- **Odłożenie (snooze)** — ukrycie wątku na określony czas
- **Szkice** — automatyczne i ręczne zapisywanie szkiców
- **Drukowanie** — widok do druku
- **Udostępnianie** — publiczny link do e-maila (przez token)

## Operacje zbiorcze

Z poziomu listy można zaznaczać wiele e-maili i wykonywać akcje zbiorcze:

- Zmiana osoby odpowiedzialnej
- Zmiana statusu
- Zmiana folderu
- Archiwizacja / usunięcie
- Dodawanie / usuwanie tagów

## Wyszukiwanie

E-maile obsługują wyszukiwanie pełnotekstowe po temacie, treści, nadawcy i odbiorcy. Filtrowanie po skrzynce, folderze, statusie, osobie odpowiedzialnej i tagach.

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

## API — E-maile

### Endpointy

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/mail/emails.json` | Lista e-maili |
| GET | `/mail/emails/:id.json` | Pojedynczy e-mail |
| POST | `/mail/emails.json` | Utworzenie e-maila (wysłanie / szkic / zaplanowanie) |
| PATCH | `/mail/emails/:id.json` | Aktualizacja e-maila |
| DELETE | `/mail/emails/:id.json` | Usunięcie e-maila |

**Autoryzacja:** `Authorization: Bearer TOKEN` (uprawnienie: **mail**)

### Pola e-maila

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `subject` | string | tak* | Temat wiadomości |
| `to` | string | tak* | Adres odbiorcy (lub `cc`/`bcc` musi być podane) |
| `content` | string | tak* | Treść wiadomości (HTML) |
| `mailbox_id` | integer | tak | ID skrzynki pocztowej |
| `from` | string | nie | Adres nadawcy (domyślnie: adres skrzynki) |
| `cc` | string | nie | Kopia (Dw) |
| `bcc` | string | nie | Ukryta kopia (Udw) |
| `reply_to` | string | nie | Adres do odpowiedzi |
| `send_status` | string | nie | Status: `sent` (wyślij), `draft` (szkic), `future` (zaplanuj) |
| `sent_at` | datetime | nie | Data wysyłki (dla `send_status: "future"`) |
| `priority` | number | nie | Priorytet (1-5) |
| `template_id` | integer | nie | ID szablonu |
| `email_id` | integer | nie | ID e-maila nadrzędnego (odpowiedź w wątku) |
| `tags` | array | nie | Tagi |
| `fields` | jsonb | nie | Własne pola |

\* Wymagane gdy `send_status` to `sent` lub `future`

### Wysyłanie e-maila

Aby e-mail został **faktycznie wysłany**, musisz podać `send_status: "sent"`. Bez tego parametru e-mail zostanie zapisany, ale nie wysłany.

```
POST /mail/emails.json
Authorization: Bearer TOKEN
Content-Type: application/json
```

```json
{
  "email": {
    "subject": "Witaj",
    "to": "klient@firma.pl",
    "content": "<p>Treść wiadomości</p>",
    "mailbox_id": 1,
    "send_status": "sent"
  }
}
```

E-mail jest kolejkowany w tle (SolidQueue) z 5-sekundowym opóźnieniem i wysyłany przez skonfigurowany serwis skrzynki (SMTP, AWS SES, EmailLabs, SendGrid).

### Zapisanie szkicu

```json
{
  "email": {
    "subject": "Szkic",
    "to": "klient@firma.pl",
    "content": "<p>Treść</p>",
    "mailbox_id": 1,
    "send_status": "draft"
  }
}
```

### Zaplanowanie wysyłki

```json
{
  "email": {
    "subject": "Zaplanowany",
    "to": "klient@firma.pl",
    "content": "<p>Treść</p>",
    "mailbox_id": 1,
    "send_status": "future",
    "sent_at": "2026-03-10T10:00:00Z"
  }
}
```

### Odpowiedź w wątku

```json
{
  "email": {
    "subject": "Re: Witaj",
    "to": "klient@firma.pl",
    "content": "<p>Odpowiedź</p>",
    "mailbox_id": 1,
    "email_id": 500,
    "send_status": "sent"
  }
}
```

### Dodatkowe endpointy

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| POST | `/mail/emails/:id/add_connected_task.json` | Powiąż z zadaniem |
| POST | `/mail/emails/:id/remove_connected_task.json` | Usuń powiązanie z zadaniem |
| POST | `/mail/emails/:id/change_priority.json` | Zmień priorytet |
| POST | `/mail/emails/:id/snooze.json` | Odłóż wątek |
| POST | `/mail/emails/:id/archive_and_next.json` | Archiwizuj i przejdź dalej |
| POST | `/mail/emails/set_as_spam.json` | Oznacz jako spam |
| POST | `/mail/emails/unspam.json` | Cofnij oznaczenie spam |
| POST | `/mail/emails/save_draft.json` | Zapisz szkic |
| GET | `/mail/emails/:id/get_content.json` | Pobierz treść e-maila |
| GET | `/mail/emails/:id/attachments.json` | Lista załączników |

### Błędy (422)

```json
{"subject": ["nie może być puste"]}
```