# Temporary Email Creator

Консольный инструмент на Python для параллельного создания временных email-адресов через **GuerrillaMail** и **Tempmail**. Скрипт поддерживает интерактивный режим, запуск одной командой, повторные попытки запросов, ограничение параллельности и сохранение результата в `.txt`.

> Используйте временные адреса только для легитимных тестов, разработки и приватных сценариев, которые разрешены правилами выбранного сервиса. Не применяйте инструмент для спама, обхода ограничений, массовой регистрации аккаунтов или нарушения пользовательских соглашений.

## Что умеет продукт

| Возможность | Описание |
|---|---|
| Два провайдера | GuerrillaMail, Tempmail или оба сразу |
| До 1000 адресов | Количество задаётся флагом `--count` или в интерактивном режиме |
| Параллельные запросы | По умолчанию 16 workers, максимум 64 |
| Надёжность | До 3 повторных попыток с экспоненциальной задержкой |
| Сохранение | Автоматическое имя `real_emails_YYYYMMDD_HHMMSS.txt` или путь через `--output` |
| Username | Поддерживается для GuerrillaMail; Tempmail создаёт случайный адрес |
| Без зависимостей | Используется только стандартная библиотека Python |

## Требования

Нужен **Python 3.10 или новее** с доступом к интернету. Сторонние пакеты устанавливать не требуется: скрипт использует стандартные модули `argparse`, `concurrent.futures`, `urllib` и `json`.

Проверьте версию Python:

```bash
python3 --version
```

## Быстрый старт

Скачайте файл `create_emails.py` из репозитория, откройте терминал в папке с файлом и запустите:

```bash
python3 create_emails.py
```

Далее программа последовательно попросит выбрать сервис, указать количество адресов и, при необходимости, задать username. После завершения можно сохранить список в файл.

## Запуск одной командой

Для создания 100 адресов через GuerrillaMail и сохранения результата:

```bash
python3 create_emails.py --provider guerrillamail --count 100 --output emails.txt
```

Для создания 1000 адресов через Tempmail:

```bash
python3 create_emails.py -p tempmail -c 1000 -o tempmail_1000.txt
```

Для работы сразу с обоими провайдерами:

```bash
python3 create_emails.py --provider both --count 1000 --output emails_both.txt
```

В режиме `both` общее количество делится между провайдерами максимально равномерно. Например, при `--count 1000` скрипт отправит 500 запросов каждому сервису.

## Все параметры

| Флаг | Значение | По умолчанию |
|---|---|---|
| `-c`, `--count` | Количество адресов от 1 до 1000 | Интерактивный ввод |
| `-p`, `--provider` | `guerrillamail`, `tempmail` или `both` | Интерактивный выбор |
| `-o`, `--output` | Путь к итоговому текстовому файлу | Автоматическое имя |
| `-u`, `--username` | Часть адреса перед `@` | Случайное значение |
| `--timeout` | Тайм-аут одного запроса в секундах | `10` |
| `--retries` | Число повторов после первой ошибки | `3` |
| `--delay` | Задержка между обработкой результатов | `0` |
| `-w`, `--workers` | Число параллельных workers от 1 до 64 | `16` |

Например, более осторожный запуск с меньшей нагрузкой и коротким тайм-аутом:

```bash
python3 create_emails.py \
  --provider guerrillamail \
  --count 50 \
  --workers 4 \
  --timeout 15 \
  --retries 2 \
  --delay 0.2 \
  --output ./results/test-emails.txt
```

## Username и ограничения провайдеров

Параметр `--username` задаёт желаемую часть адреса перед символом `@`. Для GuerrillaMail первый запрос использует указанное значение, а последующие получают суффикс с номером, например `demo`, `demo-2`, `demo-3`. Для Tempmail выбор username API не поддерживается, поэтому сервис создаёт случайный адрес и выводит соответствующее предупреждение.

Допустимый username содержит от 1 до 64 символов: латинские буквы, цифры, точку, подчёркивание и дефис. Пример:

```bash
python3 create_emails.py -p guerrillamail -c 5 -u demo-box
```

## Как выглядит результат

В терминале программа показывает прогресс, успешные адреса, ошибки и итоговую статистику:

```text
Создаем почты через Guerrillamail...
[  1/100] user@example.test
...
Скорость: 18.4 запросов/сек
Готово! Создано: 98; ошибок: 2
Сохранено в файл: emails.txt (98 почт)
```

Файл результата содержит время создания, количество успешно полученных адресов и нумерованный список email-адресов. Сохранение выполняется атомарно: сначала создаётся временный файл в той же папке, затем он заменяет итоговый файл, поэтому при ошибке записи существующий результат не затирается частично.

## Ошибки и диагностика

Если часть запросов завершилась ошибкой, проверьте подключение к интернету, доступность API-провайдера и значение `--workers`. Уменьшите параллельность, если сервис отвечает нестабильно:

```bash
python3 create_emails.py -p both -c 100 -w 4 --retries 5
```

Если адресов меньше, чем запрошено, это означает, что часть запросов не прошла после всех повторных попыток. Скрипт не подменяет ответы и не записывает некорректные строки: адрес добавляется только после проверки формата и отсутствия дубликата.

Остановить выполнение можно сочетанием `Ctrl+C`. Программа завершится с кодом `130` и не будет продолжать новые запросы.

## Важные замечания

Временные почтовые адреса не являются постоянным хранилищем почты. Доступность входящих сообщений, срок жизни ящика и возможность повторного открытия адреса зависят от конкретного провайдера. Перед использованием в тестах проверьте актуальные правила и лимиты сервиса.

Скрипт обращается к публичным endpoint-адресам, указанным в исходном коде. Их доступность и формат ответа могут измениться независимо от проекта. Поэтому для production-сценариев рекомендуется добавить собственный слой мониторинга, логирование ответов и резервный провайдер.

## Лицензия и вклад

Перед публикацией проекта добавьте в репозиторий файл лицензии, например MIT, если хотите явно разрешить свободное использование и изменение кода. Предложения по улучшению можно оформлять через Issues или Pull Requests в репозитории проекта.

## Ссылки

1. [Python `argparse` documentation](https://docs.python.org/3/library/argparse.html) — разбор аргументов командной строки.
2. [Python `concurrent.futures` documentation](https://docs.python.org/3/library/concurrent.futures.html) — параллельное выполнение задач.
3. [Python `urllib.request` documentation](https://docs.python.org/3/library/urllib.request.html) — HTTP-запросы стандартной библиотекой.