> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taimly.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Данные письма

> Параметр fields: отправитель, тема, Reply-To, SMTP, IP, PTR, тип IP, SPF/DKIM/DMARC, вложения, тело письма (text и HTML) и его оригинал. Только нужные поля в одном запросе.

По умолчанию `GET /api/spam-check/{check_id}` возвращает для каждого аккаунта только `email` и `category`. Любые данные полученного письма добавляются параметром `fields` — имена полей через запятую. Не запрошенное поле в ответ не попадает.

```bash theme={null}
curl "https://taimly.net/api/spam-check/a1b2c3d4e5f6?fields=sender_name,subject,spf,dkim,dmarc,ip_type" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Поля

| Поле | Тип | Что содержит |
| - | - | - |
| `sender_name` | string | Имя отправителя из `From`. `null`, если в `From` только адрес |
| `sender_email` | string | Адрес отправителя из `From` |
| `subject` | string | Тема письма |
| `reply_to` | string | Адрес(а) из `Reply-To` через запятую. `null`, если заголовка нет |
| `smtp` | string | Сервис, отправивший письмо в Gmail: `SendGrid`, `Amazon SES`, `Mailgun`… Нераспознанный сервис — домен отправляющего сервера |
| `sender_ip` | string | IP сервера, передавшего письмо в Gmail |
| `ptr` | string | PTR-запись (обратный DNS) `sender_ip`. `null`, если записи нет |
| `ip_type` | string | `shared` — общий пул ESP, `dedicated` — выделенный IP (PTR содержит домен отправителя), `unknown` — не удалось определить |
| `spf` | string | `pass`, `fail`, `softfail`, `neutral`, `none`, `temperror`, `permerror`, `unknown` |
| `dkim` | string | `pass`, `fail`, `neutral`, `none`, `temperror`, `permerror`, `unknown` |
| `dmarc` | string | `pass`, `fail`, `bestguesspass`, `none`, `temperror`, `permerror`, `unknown` |
| `has_attachments` | boolean | Есть ли вложения (любые файлы, включая встроенные картинки). Сами файлы не отдаются |
| `body_text` | string | Текстовая версия (`text/plain`). `null`, если её нет |
| `body_html` | string | HTML-версия (`text/html`) без изменений. `null`, если её нет |
| `raw` | string | Оригинал письма целиком — как «Показать оригинал» в Gmail: все заголовки, MIME-части и вложения |

`smtp`, `sender_ip`, `spf`, `dkim` и `dmarc` берутся из заголовков, которые добавляет сам Gmail (`Received`, `Authentication-Results`), — отправитель не может их подделать.

**Правила:**

* `email` и `category` есть всегда; поля идут в порядке таблицы.
* `null` — значения нет. Пока письмо не пришло (`category: "pending"`), все запрошенные поля — `null`.
* Неизвестное имя поля → `400` со списком допустимых.

## Пример ответа

```json theme={null}
{
  "check_id": "a1b2c3d4e5f6",
  "status": "pending",
  "received": 1,
  "total": 2,
  "results": [
    {
      "email": "inbox1@gmail.com",
      "category": "primary",
      "sender_name": "Acme",
      "subject": "Ваш заказ отправлен",
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass",
      "ip_type": "shared"
    },
    {
      "email": "inbox2@gmail.com",
      "category": "pending",
      "sender_name": null,
      "subject": null,
      "spf": null,
      "dkim": null,
      "dmarc": null,
      "ip_type": null
    }
  ]
}
```

## Тело и оригинал письма

`body_text`, `body_html` и `raw` — обычные JSON-строки. Переводы строк и кавычки экранированы по стандарту JSON (`\r\n`, `\"`), любой JSON-парсер вернёт исходный текст:

```json theme={null}
{
  "raw": "Delivered-To: inbox1+tc_a1b2c3d4e5f6@gmail.com\r\nReceived: from o1.ptr1234.sendgrid.net ...\r\nSubject: =?utf-8?b?0JLQsNGIINC30LDQutCw0Lc=?=\r\nContent-Type: multipart/alternative; boundary=\"b1\"\r\n\r\n--b1\r\n..."
}
```

`raw` — строка UTF-8. Если нужна точная байтовая копия (например, письмо в 8-битной кодировке) или просто файл, скачайте `.eml`:

```bash theme={null}
curl -o email.eml "https://taimly.net/api/spam-check/a1b2c3d4e5f6/raw?email=inbox1@gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Большие ответы

Оригинал письма весит от десятков килобайт до нескольких мегабайт (с вложениями), и в ответе он повторяется для каждого аккаунта. Сам по себе большой ответ не проблема, но лучше не тянуть тяжёлые поля на каждом опросе:

**1. Опрашивайте с лёгкими полями**

`?fields=spf,dkim,dmarc,ip_type` или вообще без `fields`, пока `status` = `pending`.

**2. Тяжёлые поля — один раз**

Когда `status` стал `complete` или `timeout`, запросите `body_text`, `body_html`, `raw` одним запросом. Или скачайте оригиналы через `/raw` только по нужным аккаунтам.

> [!TIP]
>
> Ответы API сжимаются gzip — HTML и оригиналы уменьшаются в 5–10 раз. Python `requests` и `fetch` включают сжатие сами, в `curl` добавьте `--compressed`.

> [!NOTE]
>
> Результаты и данные писем доступны **30 минут** после старта проверки. Проверку видит только ключ, который её создал.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.