mailcore-sdk 0.1.0a1__tar.gz

mailcore_sdk-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Histórico de alterações
+
+## 0.1.0a1 — 14/11/2026
+
+Primeira versão alpha local da distribuição `mailcore-sdk`, importada como
+`mailcore`. Ainda não publicada no PyPI.
+
+- Clientes síncrono e assíncrono com estado e pools próprios, fechamento explícito
+  e suporte a `with`/`async with`.
+- Dezesseis recursos principais e 151 operações por variante, com campos e nomes
+  PT-BR, preservando o contrato HTTP Mailcore.
+- Tipos de envio, lote, aceitação e configuração, `Resposta[T]` e marcador PEP 561.
+  Entidades complexas continuam parcialmente tipadas como `Resposta[Any]`.
+- Downloads autenticados, bytes e fluxos limitados; verificação local de
+  assinatura sobre o corpo bruto dos webhooks.
+- HTTPS verificado, redirecionamentos recusados, ausência de cookies/proxies do
+  ambiente, respostas limitadas e nenhuma repetição automática.
+- Exemplos opcionais Flask, FastAPI e Django com token de aplicação separado,
+  envelope fixo, idempotência externa e leitura limitada.
+- Verificação em Docker para a matriz CPython 3.11–3.15, testes de contrato,
+  transporte HTTPS e API local isolada, sem publicação ou entrega SMTP.
+
+`tempo_limite` segue a inatividade de cada etapa HTTPX. Ele não representa prazo
+total de relógio. Consulte [a cobertura](docs/cobertura.md) para os limites e o
+alcance desta versão.

mailcore_sdk-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contribuir
+
+O projeto está em alpha e distribui `mailcore-sdk`, importado como `mailcore`.
+Mantenha código e documentação em português do Brasil e preserve os nomes e
+envelopes do contrato público da API Mailcore.
+
+## Implementação
+
+- Confirme a rota, o DTO, o escopo de autorização e a resposta no backend antes
+  de acrescentar uma operação. Capacidade de API não comprova uma tela ou fluxo.
+- Mantenha paridade entre `Cliente` e `ClienteAsync`, sem estado global de
+  credenciais. Reutilize o transporte e seus pools, em vez de criar clientes a
+  cada pedido.
+- Preserve omissão, `None`, `False`, revisões e envelopes de paginação. Não
+  traduza valores do protocolo nem normalize DTOs diferentes para um só formato.
+- Atualize os tipos públicos e a cobertura sem anunciar TypedDicts completos
+  quando a resposta ainda for `Resposta[Any]`.
+- Recursos gerados são mantidos pela especificação de
+  `scripts/gerar_recursos.py`. Alterações nesse contrato devem atualizar a fonte
+  e as duas variantes, com teste de caminho, query, corpo e retorno.
+
+Os exemplos dos frameworks ficam separados do pacote principal. O SDK básico não
+deve importar Flask, FastAPI ou Django. Mantenha testes de autenticação,
+idempotência, limites e sanitização ao alterar esses exemplos.
+
+## Verificação
+
+Use o verificador Docker do projeto para executar formatação, lint, tipagem,
+testes e empacotamento, sem instalar dependências no host. A matriz é CPython
+3.11–3.15; o conjunto de frameworks respeita a compatibilidade de cada versão.
+Consulte os scripts e relatórios locais para os comandos e as imagens do ensaio.
+
+Testes que iniciam serviços devem usar rede Docker interna ou loopback do próprio
+container, dados sintéticos exclusivos, nenhuma porta publicada e limpeza dos
+recursos criados. Não use produção, tokens pessoais, SMTP ou contas reais nos
+testes do SDK. Use CA de teste confiada explicitamente; não desative a verificação
+TLS. Não publique pacotes ou aplicações durante a verificação local.
+
+Inclua verificações pertinentes à mudança: contrato e tipos, HTTP real quando o
+transporte mudar, fechamento de fluxos, cancelamento, erros sem repetição e
+ausência de segredos nas respostas. Diferencie resultados de um transporte falso,
+HTTPS sintético, API local e serviço de produção.
+
+Descreva a mudança, sua motivação, as validações executadas e limites conhecidos.
+Atualize `CHANGELOG.md` quando houver alteração pública. Relate problemas de
+segurança conforme [SECURITY.md](SECURITY.md).

mailcore_sdk-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailcore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailcore_sdk-0.1.0a1/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE README.md CHANGELOG.md SECURITY.md CONTRIBUTING.md pyproject.toml
+recursive-include src/mailcore *.py py.typed
+recursive-include docs *.md *.json
+recursive-include exemplos *.py
+prune testes
+prune scripts
+prune build
+prune .git
+global-exclude __pycache__ *.py[cod] .env .env.*

mailcore_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: mailcore-sdk
+Version: 0.1.0a1
+Summary: Cliente Python da API Mailcore com recursos síncronos e assíncronos.
+Author: Mailcore
+License-Expression: MIT
+Project-URL: Homepage, https://mailcore.com.br
+Project-URL: Repository, https://github.com/mailcore-hq/mailcore-python
+Project-URL: Issues, https://github.com/mailcore-hq/mailcore-python/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: anyio<5,>=4.8
+Dynamic: license-file
+
+# Mailcore para Python
+
+[Código-fonte](https://github.com/mailcore-hq/mailcore-python) · [Problemas e sugestões](https://github.com/mailcore-hq/mailcore-python/issues)
+
+Cliente Python da API Mailcore, em versão `0.1.0a1`. O pacote de distribuição é
+`mailcore-sdk` e o módulo importado é `mailcore`. Esta versão ainda não foi
+publicada no PyPI. Requer Python 3.11 ou superior.
+
+## Instalação local e primeiro envio
+
+Depois da verificação Docker, instale o arquivo local em sua aplicação Python:
+
+```sh
+python -m pip install /caminho/mailcore_sdk-0.1.0a1-py3-none-any.whl
+```
+
+O pip pode buscar as dependências no PyPI; o arquivo do próprio SDK é local.
+Também é possível instalar o `.tar.gz` de `dist/`, ou o checkout em modo editável
+durante o desenvolvimento da sua aplicação.
+
+```python
+import os
+from mailcore import Cliente, PedidoEmail
+
+pedido: PedidoEmail = {
+    "remetente": "Equipe <equipe@example.com>",
+    "destinatarios": ["pessoa@example.com"],
+    "assunto": "Bem-vindo",
+    "html": "<p>Sua conta está pronta.</p>",
+}
+with Cliente(chave_api=os.environ["MAILCORE_API_KEY"]) as cliente:
+    resposta = cliente.emails.enviar(pedido, chave_idempotencia="pedido-123-confirmacao")
+    print(resposta["id"])
+```
+
+Use a chave somente no servidor, com remetente de domínio verificado. A aceitação
+da intenção não comprova entrega SMTP. Preserve chave e conteúdo ao repetir uma
+intenção; o SDK não faz tentativas automáticas após erro ou timeout.
+
+## Cliente assíncrono
+
+```python
+from mailcore import ClienteAsync, PedidoEmail
+
+async def enviar(pedido: PedidoEmail) -> str:
+    async with ClienteAsync() as cliente:
+        resposta = await cliente.emails.enviar(pedido, chave_idempotencia="pedido-123-confirmacao")
+        return resposta.dados["id"]
+```
+
+Os dois clientes oferecem os mesmos recursos. As chamadas async usam HTTPX
+assíncrono nativo. Reutilize o cliente durante a vida da aplicação; `with`,
+`async with` ou `fechar()` liberam os pools. Não compartilhe um cliente async
+entre event loops. A chave pode ser uma função sem argumentos, resolvida por
+operação, para permitir rotação sem alterar um estado global.
+Um fornecedor que retorne uma chave inválida falha; não usa outra chave do ambiente.
+O pool padrão permite até 100 conexões e 20 ociosas, configuráveis por
+`maximo_conexoes` e `conexoes_ociosas`.
+
+## Respostas e erros
+
+`Resposta.dados` preserva os campos e envelopes JSON da API. `status` e
+`cabecalhos` expõem metadados HTTP, e `resposta["id"]` abrevia o acesso ao JSON.
+Bytes de downloads são `bytes`; prévias HTML são `str`. `ErroApi` preserva código
+e status da rejeição; `ErroTransporte` trata rede/prazo; `ErroResposta` trata
+conteúdo inválido ou excedido; `ErroConfiguracao` trata opções inválidas.
+
+O cliente exige TLS verificado, não segue redirecionamentos, não armazena cookies
+e não herda proxies do ambiente. Uma CA privada pode ser informada por
+`certificado_ca`. Somente loopback pode usar HTTP com `permitir_http_local=True`.
+`transporte_http` permite um adaptador HTTPX explicitamente fornecido pela aplicação;
+esse adaptador e sua política de rede são responsabilidade de quem o configura.
+
+`tempo_limite` (30 segundos por padrão) segue a semântica HTTPX: limite de
+inatividade de cada etapa de conexão, pool, escrita ou leitura. **Não é um prazo
+total de relógio**. A conexão tem limite adicional de 10 segundos. Uma aplicação
+async que precise de prazo total pode envolver a operação em `asyncio.timeout()`;
+o cancelamento é propagado e a resposta é fechada. Um prazo vencido não desfaz
+uma intenção já aceita.
+
+A resposta tem teto padrão de 16 MiB, inclusive em fluxo, ajustável por operação
+com `limite_resposta_bytes`. O JSON de pedido admite até 50 MiB para o envelope de
+importação CSV; os limites específicos de cada DTO pertencem à API. A comunicação
+solicita `Accept-Encoding: identity` e recusa codificações não negociadas.
+
+## Downloads e webhooks
+
+```python
+with Cliente() as cliente:
+    with cliente.recebimento.baixar_original_fluxo("id-da-mensagem") as fluxo:
+        with open("mensagem.eml.parcial", "wb") as arquivo:
+            for parte in fluxo:
+                arquivo.write(parte)
+```
+
+No cliente async, use `async with` e `async for`. Os fluxos preservam bytes MIME,
+exigem consumo dentro do contexto e liberam a conexão ao terminar, interromper
+ou cancelar. Só trate arquivos parciais como completos depois de sucesso.
+Downloads usam rotas autenticadas; URLs temporárias de metadados não são acessadas
+automaticamente.
+
+`verificar_assinatura(corpo_bruto, cabecalhos, segredo)` verifica HMAC-SHA256
+`svix-*`, com comparação em tempo constante e janela de cinco minutos. Passe o
+corpo bruto antes de interpretar JSON. Deduplicação e confirmação durável dos
+eventos pertencem ao consumidor.
+
+## Documentação e desenvolvimento
+
+Consulte [cobertura](docs/cobertura.md), [integrações Flask/FastAPI/Django](docs/integracoes.md)
+e [verificação](docs/verificacao.md). Não há dependência de framework no runtime
+do pacote. Instalação local usa os arquivos `.whl`/`.tar.gz` preparados em `dist/`.
+
+```sh
+sh scripts/verificar.sh
+```
+
+O desenvolvimento e os testes usam Docker, sem instalar Python, pip ou frameworks
+no host. Nenhum comando publica no PyPI ou faz deploy.

mailcore_sdk-0.1.0a1/README.md

@@ -0,0 +1,118 @@
+# Mailcore para Python
+
+[Código-fonte](https://github.com/mailcore-hq/mailcore-python) · [Problemas e sugestões](https://github.com/mailcore-hq/mailcore-python/issues)
+
+Cliente Python da API Mailcore, em versão `0.1.0a1`. O pacote de distribuição é
+`mailcore-sdk` e o módulo importado é `mailcore`. Esta versão ainda não foi
+publicada no PyPI. Requer Python 3.11 ou superior.
+
+## Instalação local e primeiro envio
+
+Depois da verificação Docker, instale o arquivo local em sua aplicação Python:
+
+```sh
+python -m pip install /caminho/mailcore_sdk-0.1.0a1-py3-none-any.whl
+```
+
+O pip pode buscar as dependências no PyPI; o arquivo do próprio SDK é local.
+Também é possível instalar o `.tar.gz` de `dist/`, ou o checkout em modo editável
+durante o desenvolvimento da sua aplicação.
+
+```python
+import os
+from mailcore import Cliente, PedidoEmail
+
+pedido: PedidoEmail = {
+    "remetente": "Equipe <equipe@example.com>",
+    "destinatarios": ["pessoa@example.com"],
+    "assunto": "Bem-vindo",
+    "html": "<p>Sua conta está pronta.</p>",
+}
+with Cliente(chave_api=os.environ["MAILCORE_API_KEY"]) as cliente:
+    resposta = cliente.emails.enviar(pedido, chave_idempotencia="pedido-123-confirmacao")
+    print(resposta["id"])
+```
+
+Use a chave somente no servidor, com remetente de domínio verificado. A aceitação
+da intenção não comprova entrega SMTP. Preserve chave e conteúdo ao repetir uma
+intenção; o SDK não faz tentativas automáticas após erro ou timeout.
+
+## Cliente assíncrono
+
+```python
+from mailcore import ClienteAsync, PedidoEmail
+
+async def enviar(pedido: PedidoEmail) -> str:
+    async with ClienteAsync() as cliente:
+        resposta = await cliente.emails.enviar(pedido, chave_idempotencia="pedido-123-confirmacao")
+        return resposta.dados["id"]
+```
+
+Os dois clientes oferecem os mesmos recursos. As chamadas async usam HTTPX
+assíncrono nativo. Reutilize o cliente durante a vida da aplicação; `with`,
+`async with` ou `fechar()` liberam os pools. Não compartilhe um cliente async
+entre event loops. A chave pode ser uma função sem argumentos, resolvida por
+operação, para permitir rotação sem alterar um estado global.
+Um fornecedor que retorne uma chave inválida falha; não usa outra chave do ambiente.
+O pool padrão permite até 100 conexões e 20 ociosas, configuráveis por
+`maximo_conexoes` e `conexoes_ociosas`.
+
+## Respostas e erros
+
+`Resposta.dados` preserva os campos e envelopes JSON da API. `status` e
+`cabecalhos` expõem metadados HTTP, e `resposta["id"]` abrevia o acesso ao JSON.
+Bytes de downloads são `bytes`; prévias HTML são `str`. `ErroApi` preserva código
+e status da rejeição; `ErroTransporte` trata rede/prazo; `ErroResposta` trata
+conteúdo inválido ou excedido; `ErroConfiguracao` trata opções inválidas.
+
+O cliente exige TLS verificado, não segue redirecionamentos, não armazena cookies
+e não herda proxies do ambiente. Uma CA privada pode ser informada por
+`certificado_ca`. Somente loopback pode usar HTTP com `permitir_http_local=True`.
+`transporte_http` permite um adaptador HTTPX explicitamente fornecido pela aplicação;
+esse adaptador e sua política de rede são responsabilidade de quem o configura.
+
+`tempo_limite` (30 segundos por padrão) segue a semântica HTTPX: limite de
+inatividade de cada etapa de conexão, pool, escrita ou leitura. **Não é um prazo
+total de relógio**. A conexão tem limite adicional de 10 segundos. Uma aplicação
+async que precise de prazo total pode envolver a operação em `asyncio.timeout()`;
+o cancelamento é propagado e a resposta é fechada. Um prazo vencido não desfaz
+uma intenção já aceita.
+
+A resposta tem teto padrão de 16 MiB, inclusive em fluxo, ajustável por operação
+com `limite_resposta_bytes`. O JSON de pedido admite até 50 MiB para o envelope de
+importação CSV; os limites específicos de cada DTO pertencem à API. A comunicação
+solicita `Accept-Encoding: identity` e recusa codificações não negociadas.
+
+## Downloads e webhooks
+
+```python
+with Cliente() as cliente:
+    with cliente.recebimento.baixar_original_fluxo("id-da-mensagem") as fluxo:
+        with open("mensagem.eml.parcial", "wb") as arquivo:
+            for parte in fluxo:
+                arquivo.write(parte)
+```
+
+No cliente async, use `async with` e `async for`. Os fluxos preservam bytes MIME,
+exigem consumo dentro do contexto e liberam a conexão ao terminar, interromper
+ou cancelar. Só trate arquivos parciais como completos depois de sucesso.
+Downloads usam rotas autenticadas; URLs temporárias de metadados não são acessadas
+automaticamente.
+
+`verificar_assinatura(corpo_bruto, cabecalhos, segredo)` verifica HMAC-SHA256
+`svix-*`, com comparação em tempo constante e janela de cinco minutos. Passe o
+corpo bruto antes de interpretar JSON. Deduplicação e confirmação durável dos
+eventos pertencem ao consumidor.
+
+## Documentação e desenvolvimento
+
+Consulte [cobertura](docs/cobertura.md), [integrações Flask/FastAPI/Django](docs/integracoes.md)
+e [verificação](docs/verificacao.md). Não há dependência de framework no runtime
+do pacote. Instalação local usa os arquivos `.whl`/`.tar.gz` preparados em `dist/`.
+
+```sh
+sh scripts/verificar.sh
+```
+
+O desenvolvimento e os testes usam Docker, sem instalar Python, pip ou frameworks
+no host. Nenhum comando publica no PyPI ou faz deploy.

mailcore_sdk-0.1.0a1/SECURITY.md

@@ -0,0 +1,43 @@
+# Segurança
+
+Esta distribuição está em alpha (`0.1.0a1`) e ainda não foi publicada no PyPI.
+O pacote de distribuição é `mailcore-sdk`; o módulo importado é `mailcore`.
+As linhas CPython adotadas na matriz são 3.11–3.15, com versões corrigidas das
+dependências do projeto.
+
+## Relatar um problema
+
+Antes da publicação, comunique vulnerabilidades por um canal privado acordado com
+os mantenedores. Informe versão, comportamento observado, impacto e uma reprodução
+mínima com dados sintéticos. Não inclua chaves, segredos de webhook, MIME de
+clientes, destinatários reais ou URLs temporárias de download em relatos públicos.
+Não há prazo de resposta ou correção garantido nesta etapa alpha.
+
+## Proteções e responsabilidades
+
+O transporte padrão verifica TLS, aceita CA privada, recusa redirecionamentos,
+solicita `identity`, recusa outra codificação e não usa cookies ou proxies do
+ambiente. A opção de HTTP é explícita e limitada a loopback. Transportes injetados
+para testes ou integração têm sua política de rede sob responsabilidade de quem
+os configura.
+
+O limite padrão de resposta é 16 MiB, também durante downloads e erros. O teto de
+JSON de pedido é 50 MiB; ele não substitui o limite de CSV de 8 MiB ou limites
+menores dos endpoints. Os timeouts HTTPX são por inatividade de etapa, não um
+prazo total. Nenhum timeout ou cancelamento comprova que um envio foi desfeito.
+
+Use chaves somente no servidor, com o menor escopo necessário. Preserve uma chave
+de idempotência estável para repetir explicitamente uma intenção. Separe clientes
+e credenciais entre organizações. Feche pools e respostas em fluxo pelos gestores
+de contexto; evite registrar corpos, dados pessoais ou cabeçalhos de autenticação.
+
+Verifique webhooks antes de interpretar seus efeitos, usando o corpo bruto e o
+segredo correto. A janela de timestamp não substitui a deduplicação do
+identificador do evento na aplicação. Original e anexos recebidos devem ser
+tratados como conteúdo externo; a disponibilidade obedece à retenção do servidor.
+Os downloads do SDK usam rotas autenticadas e não navegam automaticamente nas
+URLs temporárias contidas nos metadados.
+
+Os exemplos HTTP exigem um token próprio e enviam uma mensagem fixa. A aplicação
+que os hospedar continua responsável por entrada HTTPS, limites do servidor,
+autorização de negócio, proteção de logs e gestão de segredos.

mailcore_sdk-0.1.0a1/docs/cobertura.md

@@ -0,0 +1,148 @@
+# Cobertura do SDK Python
+
+A versão `0.1.0a1`, distribuída como `mailcore-sdk` e importada como `mailcore`,
+oferece **16 recursos principais, 30 classes e 151 operações por variante**.
+`Cliente` e `ClienteAsync` totalizam 60 classes de recursos e 302 métodos. As duas
+variantes acessam o mesmo contrato HTTP; esses números não representam 302 rotas
+distintas. Esta versão alpha ainda não foi publicada no PyPI.
+
+A superfície preserva o contrato dos SDKs Mailcore Ruby e Node. O
+[ensaio de API local](integracao-api.json) identifica a revisão do backend e o
+SHA256 das fontes usados na validação. Revisão Git e hash de conteúdo são
+identificadores distintos; o relatório registra o estado do ensaio, não uma
+afirmação sobre o HEAD atual do backend.
+
+## Recursos
+
+Os caminhos abaixo partem de uma instância de `Cliente` ou `ClienteAsync`.
+
+| Recurso principal       | Superfície incluída                                                                    | Operações por variante |
+| ----------------------- | -------------------------------------------------------------------------------------- | ---------------------: |
+| `emails`                | Enviar, listar, obter, reagendar, cancelar, eventos, consulta por idempotência e anexo |                      8 |
+| `lotes`                 | Enviar e consultar por idempotência                                                    |                      2 |
+| `dominios`              | CRUD, capacidades, tracking, registros DNS e verificação                               |                      7 |
+| `chaves_api`            | Criar, listar, renomear e revogar                                                      |                      4 |
+| `contatos`              | CRUD, lote, segmentos, tópicos, importações e exportações                              |                     20 |
+| `segmentos`             | Criar, listar, obter, atualizar e remover                                              |                      5 |
+| `topicos`               | Criar, listar, obter, atualizar e remover                                              |                      5 |
+| `propriedades_contatos` | Criar, listar, obter, atualizar e remover                                              |                      5 |
+| `modelos`               | CRUD, publicação, duplicação, prévias, testes, versões e pastas                        |                     18 |
+| `webhooks`              | CRUD, eventos, tentativas e reenvio                                                    |                      9 |
+| `campanhas`             | CRUD, duplicação, revisão, envio/cancelamento, prévias, testes e métricas              |                     15 |
+| `automacoes`            | CRUD, duplicação, parada e consulta de execuções                                       |                      9 |
+| `eventos`               | Definição, consulta, edição, remoção, listagem e envio de ocorrência                   |                      6 |
+| `recebimento`           | Consulta, anexos, original MIME e downloads comuns ou em fluxo                         |                      8 |
+| `caixas`                | CRUD, etiquetas, conversas, mensagens, respostas, encaminhamento e rascunhos           |                     28 |
+| `cli`                   | Listar e revogar concessões                                                            |                      2 |
+| **Total**               | **151 operações com a mesma superfície nas duas variantes**                            |                **151** |
+
+Os recursos subordinados usam propriedades, como `contatos.exportacoes`,
+`modelos.versoes`, `webhooks.eventos`, `caixas.conversas.emails` e `cli.concessoes`.
+Os nomes dos métodos permanecem iguais no cliente assíncrono: use
+`await cliente.emails.enviar(...)`, sem sufixo adicional no nome.
+
+## Pedidos, respostas e tipagem
+
+Pedidos e filtros aceitam `Mapping` com os campos em português do DTO HTTP, como
+`remetente`, `destinatarios`, `agendada_em` e `revisao`. Opções de transporte são
+argumentos nomeados, como `chave_idempotencia`, `tempo_limite` e
+`limite_resposta_bytes`. O servidor continua responsável pelas regras de negócio,
+permissões, revisões e limites específicos de cada endpoint.
+
+O transporte aceita valores JSON: chaves String, texto UTF-8, números finitos,
+booleanos, listas, tuplas convertidas em arrays, mapeamentos e `None`. Objetos
+arbitrários, bytes em campos JSON e números não finitos são recusados. Um campo
+omitido difere de um campo enviado com `None`; `None` e `False` permanecem no corpo.
+Na query, `None` é omitido e `False` é enviado como `false`. Identificadores são
+codificados como segmentos, preservando o prefixo da API.
+
+As respostas usam `Resposta[T]`, com `dados`, `status` e `cabecalhos` separados.
+JSON mantém chaves String, inclusive nos objetos internos; resposta sem conteúdo
+pode produzir `dados=None`. Downloads comuns retornam `Resposta[bytes]` e prévias
+textuais usam `str`. `resposta["id"]` consulta o campo em `dados`.
+
+Há tipos públicos para envio direto/modelo, anexos, lote, respostas de aceitação,
+configuração e opções, além do marcador PEP 561 `py.typed`. Entre eles estão
+`PedidoEmail`, `PedidoEmailLote`, `RespostaEnvio` e `RespostaLote`. Essa tipagem não
+é um schema completo de todas as entidades: recursos complexos ainda aceitam
+`Mapping[str, Any]` e retornam `Resposta[Any]`, preservando o DTO do servidor.
+TypedDict não substitui a validação de runtime nem a validação da API.
+
+A paginação é explícita: uma chamada consulta uma página e conserva o envelope e
+os cursores recebidos. O SDK não percorre páginas automaticamente nem uniformiza
+envelopes distintos do backend.
+
+## Contratos relevantes
+
+- Envio direto permite composição Cc/Cco, cabeçalhos e anexos Base64/CID conforme
+  o DTO. Envio por modelo tem seu próprio formato, sem misturar campos exclusivos
+  da composição direta. O cliente não baixa anexos remotos por iniciativa própria.
+- Lotes seguem o array e a aceitação atômica do backend, sem dividir pedidos nem
+  repetir automaticamente. Agendamento usa `agendada_em` ISO 8601 com fuso e as
+  regras de estado do servidor. Aceitação não comprova entrega SMTP.
+- Importações recebem CSV UTF-8 no corpo JSON. O limite de CSV é 8 MiB no contrato
+  da API; o transporte admite JSON de até 50 MiB para acomodar escapes. Esse teto
+  geral não amplia limites menores dos demais endpoints.
+- Modelos, campanhas, automações e caixas preservam revisões, estados e campos
+  anuláveis. Parar ou cancelar não desfaz efeitos já aceitos pelo servidor.
+- A chave secreta de API só aparece na criação. Revogação pode retornar resposta
+  vazia. Concessões CLI incluem consulta/revogação, sem iniciar autenticação
+  interativa ou renovar tokens.
+
+## Recebimento e fluxos
+
+Original MIME, anexos recebidos e exportações usam rotas fixas autenticadas. URLs
+temporárias presentes nos metadados são capacidades sensíveis; o SDK não as segue
+automaticamente nem transfere a credencial para um destino informado pela API.
+Retenção e disponibilidade do conteúdo são determinadas pelo servidor.
+
+`baixar_original_fluxo`, `baixar_anexo_fluxo` e `baixar_fluxo` devolvem gestores de
+contexto. Use `with` no cliente síncrono e `async with` no assíncrono; dentro do
+contexto, consuma bytes por `for` ou `async for`. O leitor expõe `status`,
+`cabecalhos` e `total_bytes`. O gestor assíncrono não recebe `await` antes de
+`async with`. A saída do contexto fecha a resposta, inclusive no encerramento
+antecipado do consumo.
+
+O teto padrão de resposta é **16 MiB**, inclusive em fluxo e em respostas de erro;
+`limite_resposta_bytes` permite ajustar a operação. O limite é aplicado durante a
+leitura, não apenas depois de acumular o conteúdo.
+
+## Transporte e limites
+
+Cada cliente reutiliza seu pool HTTPX e deve ser fechado com contexto ou
+`fechar()`; `ClienteAsync` usa fechamento aguardado e também oferece
+`fechar_async()`. A comunicação padrão usa HTTPS verificado, recusa
+redirecionamentos, não armazena cookies e não herda proxies do ambiente. Uma CA
+privada pode ser configurada. HTTP é uma opção explícita restrita a loopback para
+ensaios locais. Um transporte HTTP injetado tem sua política de rede sob controle
+de quem o fornece.
+
+O SDK solicita `Accept-Encoding: identity` e recusa codificações não negociadas.
+Isso preserva os bytes de MIME, anexos e CSV e mantém o limite de leitura
+previsível. Nenhuma falha produz repetição automática; preserve chave e conteúdo
+ao decidir repetir uma intenção.
+
+`tempo_limite`, por padrão **30 segundos**, limita a inatividade de cada etapa
+HTTPX: pool, conexão, escrita ou leitura. A conexão usa no máximo o menor valor
+entre esse limite e `tempo_conexao`, cujo padrão é **10 segundos**. **Não existe
+um prazo total de relógio embutido**: um fluxo que continua avançando pode durar
+mais. A aplicação assíncrona pode envolver a operação em `asyncio.timeout()` quando
+precisar desse prazo total. Cancelar a espera não desfaz uma intenção aceita.
+
+## Alcance da validação
+
+A matriz do projeto é CPython **3.11–3.15**. Os exemplos opcionais exercitam Flask
+e Django síncronos e FastAPI assíncrono; o exemplo Django é uma view direta, sem
+implementar um backend de email. Veja [as integrações](integracoes.md) para as
+versões e seus limites. SDK e frameworks têm contratos de compatibilidade distintos.
+
+Os testes de contrato conferem as 151 operações de cada variante com um
+transporte coletor. Ensaios HTTPS sintéticos verificam o transporte; o
+[relatório de API local](integracao-api.json) registra a execução contra backend
+isolado com dados sintéticos. Esses resultados não demonstram entrega SMTP,
+produção, capacidade de escala ou deploy cloud.
+
+Esta cobertura descreve a seleção implementada, não toda a API do produto.
+Não inclui recursos globais de logs, uso ou supressões, autorização OAuth
+interativa, helpers de sessão/dashboard nem renderização React. Campos adicionais
+dos DTOs não implicam métodos ou fluxos novos no SDK.

mailcore_sdk-0.1.0a1/docs/integracao-api-interrupcao.json

@@ -0,0 +1,27 @@
+{
+  "data_utc": "2026-11-14T14:29:54.661686+00:00",
+  "resultado": "falhou",
+  "ambiente": "api_postgres_tls_exclusivos_sem_worker_sem_portas",
+  "instalacao_host": false,
+  "rede_interna": true,
+  "portas_publicadas": false,
+  "worker_executado": false,
+  "smtp_executado": false,
+  "deploy_executado": false,
+  "tls_api_verificado": false,
+  "tls_postgres": "nao_verificado",
+  "cenarios": [],
+  "etapa": "preparar_identidades",
+  "imagens": {
+    "cliente": "sha256:41ff4552dda1fb72f2b97f34efd9a3742a0c31d9a8b19309846a29b0fd74cce4",
+    "api_runtime": "sha256:158e95e9b87f2a126c038e6931b2f956fe6120f3566fd047a29250bd7783ff33",
+    "compilador": "sha256:8fa55b2f3ddf97471ab6a767bfa3f37e6bad0986ba823e75fea57e2a2a5c3073",
+    "postgres": "sha256:f1ea2a1a4fb7b68d4836be1fdcb8a6466a89b072158bf9d97663600538c294c5"
+  },
+  "backend_revisao": "c00da750773435140fda072b88c7070fdfda22c7",
+  "backend_fontes_sha256": "d31c825268a64c858276827f47d27e506f543421327f487d7165e511359e248f",
+  "backend_fontes_alterados": false,
+  "api_compilada_neste_ensaio": true,
+  "falha": "Ensaio interrompido; recursos exclusivos serão removidos.",
+  "limpeza_concluida": true
+}

mailcore_sdk-0.1.0a1/docs/integracao-api.json

@@ -0,0 +1,52 @@
+{
+  "data_utc": "2026-11-14T14:58:46.486693+00:00",
+  "resultado": "aprovado",
+  "ambiente": "api_postgres_tls_exclusivos_sem_worker_sem_portas",
+  "instalacao_host": false,
+  "rede_interna": true,
+  "portas_publicadas": false,
+  "worker_executado": false,
+  "smtp_executado": false,
+  "deploy_executado": false,
+  "tls_api_verificado": true,
+  "tls_postgres": "verify-full",
+  "cenarios": [
+    "chaves_full_sending_escopo_repr",
+    "envio_composto_idempotencia_409_download_cancelamento",
+    "envio_async_replay_mesma_intencao",
+    "lote_atomico_repeticao_conflito",
+    "dominios_capacidades_tracking_crud",
+    "contatos_nulos_catalogos_exportacao_csv_fluxo",
+    "modelos_pastas_versoes_previa_publicacao_cas",
+    "marketing_crud_sem_disparo",
+    "caixas_etiquetas_rascunhos_cas_sem_envio",
+    "recebimento_mime_real_pendente_bytes_fluxo",
+    "recebimento_async_bytes_contexto_fluxo",
+    "cli_revogacao_e_limpeza_crud"
+  ],
+  "etapa": "concluido",
+  "imagens": {
+    "cliente": "sha256:a8a48dc98d737ee421afe7422e846c5bf17bdc14033170a4380eae2cd9c5f0d9",
+    "api_runtime": "sha256:158e95e9b87f2a126c038e6931b2f956fe6120f3566fd047a29250bd7783ff33",
+    "compilador": "sha256:8fa55b2f3ddf97471ab6a767bfa3f37e6bad0986ba823e75fea57e2a2a5c3073",
+    "postgres": "sha256:f1ea2a1a4fb7b68d4836be1fdcb8a6466a89b072158bf9d97663600538c294c5"
+  },
+  "backend_revisao": "27789fd7c7bfbeaaed4a4f517e417921ae8ca60b",
+  "backend_fontes_sha256": "d31c825268a64c858276827f47d27e506f543421327f487d7165e511359e248f",
+  "backend_fontes_alterados": false,
+  "api_compilada_neste_ensaio": true,
+  "api_binario_sha256": "3cd977ab90dbfcc0067b7d0b85d120ae9132f4e873cc223298f901fc1dbd35bf",
+  "migracoes_aplicadas": 23,
+  "python": "3.12.16",
+  "httpx": "0.28.1",
+  "recebimento_processado_por_worker": false,
+  "async_exercitado": true,
+  "async_envio_repetiu_intencao_existente": true,
+  "persistencia_sintetica": {
+    "mensagens": 3,
+    "tarefas_envio": 3,
+    "recebidos": 1,
+    "recebidos_pendentes": 1
+  },
+  "limpeza_concluida": true
+}