Metadata-Version: 2.4
Name: send-email-dev
Version: 0.1.0
Summary: App Django reutilizavel para envio de emails via SMTP com suporte a anexos locais e por URL.
Author: yagoo-alphabeto
License: MIT
Project-URL: Homepage, https://github.com/yagoo-alphabeto/send-email-dev
Project-URL: Repository, https://github.com/yagoo-alphabeto/send-email-dev
Keywords: django,email,smtp,reusable-app
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: python-decouple>=3.8
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14; extra == "drf"
Dynamic: license-file

# send-email-dev

App Django reutilizavel para envio de e-mails via SMTP, com suporte a:

- Corpo em **texto + HTML** (alternative) automatico, com rodape configuravel
- **Anexos locais** (caminho no disco)
- **Anexos por URL** (faz o download e anexa)
- Configuracao 100% via **variaveis de ambiente** (`.env`) usando `python-decouple`
- Comando de **setup automatico** que cria/atualiza o `.env` do projeto
- (Opcional) Endpoint REST pronto para enviar e-mail (requer DRF)

---

## Instalacao

```bash
pip install send-email-dev
```

Se quiser tambem o endpoint REST pronto, instale com o extra `drf`:

```bash
pip install "send-email-dev[drf]"
```

No `requirements.txt`:

```txt
send-email-dev==0.1.0
```

> Importante: o nome de **instalacao** e `send-email-dev`, mas o nome de **import** dentro do codigo Python e `django_email_sender` (ver exemplos abaixo).

---

## Configuracao no projeto

### 1. Adicione em `INSTALLED_APPS`

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "django_email_sender",
]
```

### 2. Rode o setup

```bash
python manage.py setup_email_sender
```

Isso cria (ou complementa) o `.env` na raiz do projeto com as variaveis:

```env
SMTP_SERVIDOR=smtp.zoho.com
SMTP_PORTA=465
SMTP_USAR_SSL=True
EMAIL_USUARIO=seu_email@exemplo.com
EMAIL_SENHA=sua_senha_de_app
EMAIL_RODAPE_HTML=Enviado via django-email-sender
```

Opcoes do comando:

| Flag      | Descricao                                                  |
| --------- | ---------------------------------------------------------- |
| `--force` | Sobrescreve variaveis ja existentes no `.env`              |
| `--path`  | Define um caminho alternativo para o `.env`                |

### 3. Preencha as credenciais reais no `.env`

> Em provedores como Gmail/Zoho/Outlook, use **senha de app**, nao a senha pessoal.

### 4. (Opcional) Carregue o `.env` no `settings.py`

Como a lib usa `python-decouple`, basta ter o arquivo `.env` na raiz que ele e lido automaticamente — voce nao precisa configurar nada extra no `settings.py`.

---

## Uso da funcao

Em qualquer view, service, task ou shell:

```python
from django_email_sender import enviar_email

enviar_email(
    destinatario="cliente@exemplo.com",
    assunto="Bem-vindo!",
    corpo="Ola, obrigado por se cadastrar.",
)
```

### Com anexo local

```python
enviar_email(
    destinatario="cliente@exemplo.com",
    assunto="Sua nota fiscal",
    corpo="Segue em anexo a nota fiscal.",
    anexo_path="/caminho/local/nota_fiscal.pdf",
)
```

### Com anexo via URL

```python
enviar_email(
    destinatario="cliente@exemplo.com",
    assunto="Documento",
    corpo="Segue o documento solicitado.",
    anexo_url="https://meu-bucket.s3.amazonaws.com/doc.pdf",
)
```

### Sobrescrevendo a configuracao por chamada

```python
from django_email_sender import ConfiguracaoSMTP, enviar_email

cfg = ConfiguracaoSMTP(
    servidor="smtp.gmail.com",
    porta=587,
    usar_ssl=False,
    usuario="outro@exemplo.com",
    senha="senha-de-app",
)

enviar_email(
    destinatario="cliente@exemplo.com",
    assunto="Teste",
    corpo="Mensagem usando outra conta SMTP",
    smtp_config=cfg,
)
```

### Verificando a conexao SMTP

```python
from django_email_sender import verificar_conexao_smtp

if verificar_conexao_smtp():
    print("SMTP OK")
else:
    print("SMTP indisponivel")
```

---

## (Opcional) Endpoint REST

Se voce ja usa **Django REST Framework**, pode plugar a URL pronta no seu projeto:

```python
# urls.py do projeto
from django.urls import include, path

urlpatterns = [
    # ...
    path("emails/", include("django_email_sender.urls")),
]
```

E ja tera disponivel:

`POST /emails/enviar/`

```json
{
  "destinatario": "cliente@exemplo.com",
  "assunto": "Assunto",
  "corpo": "Texto do email",
  "anexoPath": "/caminho/local/arquivo.pdf",
  "anexoUrl":  "https://exemplo.com/arquivo.pdf"
}
```

Resposta de sucesso:

```json
{
  "success": true,
  "destinatario": "cliente@exemplo.com",
  "assunto": "Assunto",
  "status": "ENVIADO"
}
```

> Se voce nao usa DRF, basta nao incluir a URL. A funcao `enviar_email` continua funcionando normalmente, ela nao depende de DRF.

---

## API publica

Tudo importavel direto do pacote `django_email_sender`:

```python
from django_email_sender import (
    enviar_email,
    verificar_conexao_smtp,
    ConfiguracaoSMTP,
    carregar_configuracao_smtp,
)
```

| Item                          | Descricao                                                      |
| ----------------------------- | -------------------------------------------------------------- |
| `enviar_email(...)`           | Envia um e-mail (texto + HTML), opcionalmente com anexo        |
| `verificar_conexao_smtp(...)` | Testa se o SMTP responde com as credenciais atuais             |
| `ConfiguracaoSMTP`            | Dataclass para criar configuracoes SMTP customizadas           |
| `carregar_configuracao_smtp`  | Le as variaveis do `.env` e devolve um `ConfiguracaoSMTP`      |

---

## Variaveis de ambiente

| Variavel             | Padrao                              | Descricao                                 |
| -------------------- | ----------------------------------- | ----------------------------------------- |
| `SMTP_SERVIDOR`      | `smtp.zoho.com`                     | Host do servidor SMTP                     |
| `SMTP_PORTA`         | `465`                               | Porta SMTP                                |
| `SMTP_USAR_SSL`      | `True`                              | `True` = SSL direto; `False` = STARTTLS   |
| `EMAIL_USUARIO`      | *(obrigatorio)*                     | E-mail remetente / usuario do SMTP        |
| `EMAIL_SENHA`        | *(obrigatorio)*                     | Senha de app do remetente                 |
| `EMAIL_RODAPE_HTML`  | `Enviado via django-email-sender`   | Texto do rodape HTML acrescentado ao corpo|

---

## Licenca

MIT — veja [LICENSE](LICENSE).
