mailcore 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48fb7eb69d256776ed0f0fc87263bae696e305d26951713a68b3728e8bd92a2d
+  data.tar.gz: 0dc87a1ed77dce322edbe22c410c87644a1a1cde50051ac515b19f85439764fe
+SHA512:
+  metadata.gz: 901090c17a27114d7466eacc4a77c78d91ba21f2951331f2c01941b1e003bab4b8f4691095d291358284a3bf23401e175698c03de33144388a3ecd5420876d4d
+  data.tar.gz: c5bdefe691e0a3b5be1cc70127dfe3ecc856170b20391eaba9beb2b73684291eb0780fff1c9b6308dea2e1f3c707a8ca0c9428a944efc3c126f13841f0ab38a3

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Alterações
+
+## 0.1.0.alpha.1 — 14/11/2026
+
+- Primeira gem Ruby Mailcore, com 151 operações correspondentes ao contrato público
+  já integrado pelo SDK Node.
+- Cliente por instância, chave estática ou Proc resolvida por operação, respostas
+  com metadados e exceções próprias.
+- TLS verificado, recusa de redirecionamento, prazos totais e limites de resposta,
+  com retries implícitos de Net::HTTP desabilitados.
+- Downloads binários e por blocos, HMAC-SHA256 de webhooks e integração Rails
+  opcional com Action Mailer e Action Mailbox.
+- Desenvolvimento, matriz de testes e preparação da distribuição em Docker.
+
+Esta versão é alpha e não foi publicada no RubyGems.

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contribuir
+
+Use código, comentários e documentação em português do Brasil, preservando nomes
+exigidos pelos protocolos Ruby/Rails/HTTP. Recursos ficam em `lib/mailcore/recursos`;
+o transporte centraliza autenticação, TLS, erros, prazos e limites.
+
+O servidor é a autoridade para os DTOs, escopos, permissões e transições. Compare
+novas operações com as rotas públicas do backend antes de implementá-las. Não
+normalize envelopes diferentes nem transforme ausência de campo em `nil` no JSON.
+
+Execute `sh scripts/verificar.sh` com Docker Linux. Não é necessário instalar
+ferramentas no host. Mantenha a matriz de runtimes, lockfile de desenvolvimento,
+testes de contrato/protocolo e instalação da gem coerentes. Rails é opcional:
+carregar o cliente puro não pode exigir Action Mailer ou Action Mailbox.
+
+Use dados sintéticos em testes. Não inicie workers/SMTP ou publique portas para
+verificar o cliente. A integração local real usa banco e API exclusivos e remove
+seus recursos. Registre o alcance observado sem atribuir ao laboratório prova de
+entrega, desempenho cloud ou configuração de uma conta de produção.
+
+Os comandos de verificação não devem publicar pacotes ou fazer deploy. Uma
+implantação posterior no Mailcore precisa ser testada no ambiente de produção.

data/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.

data/README.md

@@ -0,0 +1,185 @@
+# Mailcore para Ruby
+
+[Código-fonte](https://github.com/mailcore-hq/mailcore-ruby) · [Problemas e sugestões](https://github.com/mailcore-hq/mailcore-ruby/issues)
+
+Cliente Ruby da API Mailcore, com integração opcional com Rails. Versão
+alpha `0.1.0.alpha.1`. Requer Ruby 3.3 ou superior.
+Cada instância mantém sua configuração; pedidos concorrentes não compartilham
+credenciais ou estado de envio.
+
+## Instalação
+
+Instale a versão alpha pelo RubyGems:
+
+```sh
+gem install mailcore --version 0.1.0.alpha.1 --pre
+```
+
+Com Bundler, adicione ao Gemfile da aplicação:
+
+```ruby
+gem 'mailcore', '0.1.0.alpha.1'
+```
+
+### Desenvolvimento e instalação local
+
+A verificação Docker gera `pkg/mailcore-0.1.0.alpha.1.gem`. Em uma aplicação Ruby:
+
+```sh
+gem install /caminho/mailcore-0.1.0.alpha.1.gem
+```
+
+O comando pode buscar dependências no RubyGems. Outra opção é apontar o Gemfile
+da aplicação para este checkout e executar Bundler:
+
+```ruby
+gem 'mailcore', path: '/caminho/libs-mailcore/mailcore-ruby'
+```
+
+Não é necessário instalar Rails para utilizar o cliente. As dependências de
+runtime são `net-http`, `json`, `openssl`, `base64` e `timeout`; o pacote não
+inclui um cliente HTTP compilado próprio. A faixa JSON 2.x mantém compatibilidade
+com a versão Rails exercitada pelos testes.
+
+## Primeiro envio
+
+Configure `MAILCORE_API_KEY` somente no servidor. Use domínio verificado e uma
+chave autorizada para o remetente.
+
+```ruby
+require 'mailcore'
+
+cliente = Mailcore::Cliente.new(chave_api: ENV.fetch('MAILCORE_API_KEY'))
+pedido = {
+  remetente: 'Equipe <equipe@example.com>',
+  destinatarios: ['pessoa@example.com'],
+  assunto: 'Bem-vindo',
+  html: '<p>Sua conta está pronta.</p>',
+  texto: 'Sua conta está pronta.'
+}
+resposta = cliente.emails.enviar(pedido, chave_idempotencia: 'pedido-123-confirmacao')
+puts resposta[:id]
+```
+
+`202` confirma a aceitação da intenção; a entrega é acompanhada pelos eventos da
+mensagem ou webhooks. Reutilize a mesma chave e o mesmo conteúdo ao repetir a
+mesma intenção. A biblioteca não repete requisições automaticamente, inclusive
+após timeout, `429` e desconexão. Um timeout não desfaz uma intenção aceita.
+
+Anexos usam `nome`, `tipo_conteudo`, `conteudo_base64` e, no envio composto,
+`id_conteudo` opcional para CID. O lote aceita de 1 a 100 mensagens, em uma única
+operação atômica; não divide pedidos nem aceita anexos, Cc/Cco ou cabeçalhos de
+mensagem. Agendamento usa `agendada_em` ISO 8601 com fuso. As regras de domínio,
+permissões e limites do DTO são validadas pelo servidor.
+
+## Resultados, erros e opções
+
+As operações devolvem `Mailcore::Resposta`: `dados` contém o JSON da API com
+chaves simbolizadas recursivamente; `status` e `cabecalhos` preservam metadados
+HTTP. `resposta[:id]` abrevia `resposta.dados[:id]`. Listas mantêm os envelopes
+originais (`dados`, `proximo`, `proximo_cursor`, `tem_mais`, conforme a rota).
+Nenhuma paginação é percorrida automaticamente.
+
+```ruby
+begin
+  pagina = cliente.contatos.listar({ limite: 20 })
+  proximo = pagina.dados[:proximo_cursor]
+rescue Mailcore::ErroApi => erro
+  # erro.codigo, erro.status e erro.cabecalhos['retry-after']
+rescue Mailcore::ErroTransporte => erro
+  # Confirme a intenção antes de decidir repetir um envio ambíguo.
+end
+```
+
+`ErroApi` preserva códigos e mensagens JSON públicos do servidor.
+`ErroResposta` identifica JSON inválido e limites excedidos.
+`ErroTransporte` identifica falhas de comunicação, resposta incompleta ou prazo; configuração inválida
+gera `ErroConfiguracao`. As mensagens de transporte não reproduzem credenciais
+ou corpos recebidos. Erros de API podem conter dados privados; registre somente
+os campos necessários.
+
+Todas as operações aceitam as palavras-chave `chave_idempotencia`,
+`tempo_limite` (segundos), `limite_resposta_bytes` e `cabecalhos` adicionais.
+Cabeçalhos de autenticação, protocolo e idempotência são reservados pelo cliente.
+O prazo total padrão é 30 segundos, conexão até 10 segundos e resposta até 16 MiB.
+O teto JSON de pedido é 50 MiB, para comportar o envelope de importação CSV;
+cada rota aplica seu limite específico no servidor.
+
+```ruby
+cliente = Mailcore::Cliente.new(
+  chave_api: -> { ENV.fetch('MAILCORE_API_KEY') },
+  url_base: 'https://mailcore.com.br/v1',
+  tempo_limite: 30,
+  tempo_conexao: 10
+)
+```
+
+Uma chave em `Proc` é resolvida a cada operação, permitindo rotação. Use instâncias
+distintas para credenciais distintas; configure o módulo global somente no boot.
+O cliente exige HTTPS, verifica certificado e hostname e recusa redirecionamentos.
+Não herda proxies do ambiente. CAs privadas podem ser informadas por
+`certificado_ca: '/caminho/ca.crt'`; TLS permanece verificado. HTTP só é permitido
+em loopback com `permitir_http_local: true`, para testes explícitos.
+
+## Downloads e webhooks
+
+Downloads completos devolvem `String` em `Encoding::BINARY`, preservando MIME,
+CSV e anexos. Os métodos com sufixo `_fluxo` exigem bloco e entregam partes de
+forma síncrona, respeitando o ritmo do consumidor e o teto de bytes. A resposta
+final informa o total em `dados`. Prazo e tamanho continuam ativos até terminar.
+
+```ruby
+File.open('/caminho/mensagem.eml.parcial', 'wb') do |arquivo|
+  cliente.recebimento.baixar_original_fluxo('id-da-mensagem') do |parte|
+    arquivo.write(parte)
+  end
+end
+```
+
+Só trate o arquivo como completo depois de sucesso; uma falha pode deixar partes
+já escritas. Downloads usam rotas autenticadas da API; URLs temporárias retornadas
+em metadados não são acessadas automaticamente.
+
+```ruby
+evento = Mailcore.verificar_assinatura(
+  corpo_bruto: corpo_recebido_sem_alteracoes,
+  cabecalhos: cabecalhos_recebidos,
+  segredo: ENV.fetch('MAILCORE_WEBHOOK_SECRET')
+)
+```
+
+A verificação usa HMAC-SHA256, cabeçalhos `svix-*`, comparação em tempo constante
+e janela temporal de cinco minutos. Corpo alterado, cabeçalhos ambíguos e
+timestamps vencidos/futuros são recusados. Deduplicação dos eventos e confirmação
+durável pertencem ao consumidor; uma assinatura válida não torna a ação idempotente.
+
+## Rails e demais recursos
+
+O [guia Rails](docs/rails.md) cobre Action Mailer e Action Mailbox, incluindo
+HTML/texto, anexos/CID e recebimento autenticado. Rails e Mail são opcionais para
+a gem; os adaptadores usam os componentes já instalados na aplicação.
+O [exemplo Sinatra](docs/sinatra.md) demonstra uma rota privada de envio com
+destino fixo, usando o mesmo cliente Ruby e a instalação Sinatra da aplicação.
+
+A [cobertura](docs/cobertura.md) lista os recursos e contratos. O cliente inclui
+envio, lote, domínios, chaves, contatos, segmentos, tópicos, propriedades,
+importações/exportações, modelos, campanhas, automações, eventos, webhooks,
+recebimento, caixas e concessões CLI. Não converte métodos privados do dashboard
+em API pública nem cria capacidades ausentes no servidor.
+
+## Desenvolver e verificar com Docker
+
+Requisitos do host: shell POSIX e Docker Linux acessível ao usuário.
+Ruby, Bundler, Rails e ferramentas de compilação rodam dentro das imagens:
+
+```sh
+sh scripts/verificar.sh
+```
+
+O comando verifica a matriz Ruby 3.3, 3.4 e 4.0, prepara a gem e confere sua
+instalação. Os testes de protocolo usam dados sintéticos, TLS verificado e nenhuma
+porta publicada. A [verificação](docs/verificacao.md) distingue os testes de
+contrato, HTTPS, Rails e integração com a API real local.
+
+Publicação no RubyGems e deploy não são executados por esses comandos.
+Leia [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) e [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,28 @@
+# Segurança
+
+Mantenha as chaves no servidor, em variáveis protegidas ou gerenciador de segredos.
+Nunca as inclua no cliente de navegador, Git, URLs, relatórios ou mensagens de log.
+Use chaves com os escopos e domínios necessários. Revogação e autorização atual
+continuam sendo controladas pela API.
+
+HTTPS é obrigatório, com verificação de cadeia/hostname. O SDK não segue
+redirecionamentos, não envia cookies, não herda proxies do ambiente e não
+permite substituir cabeçalhos reservados. A opção HTTP de teste se limita a
+loopback explicitamente autorizado. Uma CA privada não desabilita a verificação TLS.
+
+Valide assinaturas sobre o corpo bruto antes de processar eventos. Preserve
+deduplicação durável, autorização da aplicação e limites no servidor HTTP que
+recebe o webhook. Repetições legítimas podem ocorrer dentro da janela de assinatura.
+No Action Mailbox, configure armazenamento protegido e retenção de mensagens.
+
+Não registre corpos MIME/JSON, endereços, URLs temporárias ou segredos para
+diagnosticar falhas. A gem não registra requisições automaticamente. `inspect`
+de configuração, cliente, transporte e resposta omite credenciais/conteúdo.
+
+Em caso de falha em download por blocos, descarte o arquivo parcial antes de
+usá-lo. Em caso de timeout de envio, consulte a intenção por idempotência antes de
+repetir. Não há repetição automática no transporte; tarefas Rails podem possuir
+sua própria política de repetição, que deve preservar a chave/intenção.
+
+Relate vulnerabilidades pelo canal privado de manutenção do projeto, com uma
+reprodução sintética. Não publique credenciais ou dados de clientes em issues.

data/app/controllers/action_mailbox/ingresses/mailcore/inbound_emails_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  module Ingresses
+    module Mailcore
+      class InboundEmailsController < ::ActionMailbox::BaseController
+        LIMITE_EVENTO_BYTES = ::Mailcore::LimiteIngress::LIMITE_BYTES
+        class_attribute :cliente_mailcore, instance_accessor: false, default: nil
+
+        def create
+          return head :content_too_large if request.content_length.to_i > LIMITE_EVENTO_BYTES
+
+          corpo = request.body.read(LIMITE_EVENTO_BYTES + 1).to_s
+          return head :content_too_large if corpo.bytesize > LIMITE_EVENTO_BYTES
+
+          segredo = segredo_assinatura
+          return head :service_unavailable unless segredo.is_a?(String) && !segredo.empty?
+
+          evento = ::Mailcore.verificar_assinatura(
+            corpo_bruto: corpo,
+            cabecalhos: {
+              'svix-id' => request.headers['svix-id'],
+              'svix-timestamp' => request.headers['svix-timestamp'],
+              'svix-signature' => request.headers['svix-signature']
+            },
+            segredo: segredo
+          )
+          return head :no_content unless evento[:type] == 'email.received'
+
+          dados = evento[:data]
+          unless dados.is_a?(Hash) && dados[:email_id].is_a?(String) && !dados[:email_id].empty?
+            return head :unprocessable_entity
+          end
+
+          fonte = ::Mailcore::MensagemActionMailbox.new(
+            email_id: dados[:email_id], destinatarios: dados[:to],
+            cliente: self.class.cliente_mailcore || ::Mailcore.cliente
+          ).original
+          ::ActionMailbox::InboundEmail.create_and_extract_message_id!(fonte)
+          head :no_content
+        rescue ::Mailcore::ErroAssinatura
+          head :unauthorized
+        rescue ::Mailcore::ErroEnvelopeActionMailbox
+          head :unprocessable_entity
+        rescue ::Mailcore::Erro
+          head :service_unavailable
+        end
+
+        private
+
+        def segredo_assinatura
+          segredo = Rails.application.credentials.dig(:action_mailbox, :mailcore_segredo) ||
+                    ::Mailcore.configuracao.segredo_webhook
+          segredo.respond_to?(:call) ? segredo.call : segredo
+        end
+      end
+    end
+  end
+end

data/docs/cobertura.md

@@ -0,0 +1,140 @@
+# Cobertura da gem Mailcore
+
+A versão `0.1.0.alpha.1` reúne **16 recursos principais, 30 classes de recursos e
+151 métodos HTTP**. O contrato foi conferido no backend
+`e001da831365c536f5764dc703fb7a03964f807f` e no SDK Node
+`a234dc2d6f22389f8a57046a142d82a4a4feddf5`, em 14/11/2026. A superfície Ruby
+preserva os caminhos, campos e envelopes selecionados nessa conferência.
+
+Os nomes abaixo partem de uma instância `cliente = Mailcore::Cliente.new(...)`.
+Pedidos e filtros são `Hash` posicionais; opções da operação são palavras-chave,
+como `chave_idempotencia:`, `tempo_limite:`, `limite_resposta_bytes:` e
+`cabecalhos:`. Os prazos usam segundos. Os métodos síncronos retornam
+`Mailcore::Resposta`, com `dados`, `status` e `cabecalhos`; `resposta[:id]`
+consulta a chave correspondente em `dados`.
+
+## Recursos e métodos
+
+| Recurso                      | Métodos                                                                                                                                                                                              |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `emails`                     | `enviar`, `listar`, `obter`, `reagendar`, `cancelar`, `eventos`, `obter_por_idempotencia`, `baixar_anexo`                                                                                            |
+| `lotes`                      | `enviar`, `obter_por_idempotencia`                                                                                                                                                                   |
+| `dominios`                   | `criar`, `listar`, `obter`, `atualizar`, `registros_dns`, `verificar`, `remover`                                                                                                                     |
+| `chaves_api`                 | `criar`, `listar`, `renomear`, `revogar`                                                                                                                                                             |
+| `contatos`                   | `criar`, `listar`, `obter`, `atualizar`, `remover`, `adicionar_em_lote`, `alterar_em_lote`                                                                                                           |
+| `contatos.segmentos`         | `listar`, `adicionar`, `remover`                                                                                                                                                                     |
+| `contatos.topicos`           | `listar`, `atualizar`                                                                                                                                                                                |
+| `contatos.importacoes`       | `prever`, `criar`, `obter`                                                                                                                                                                           |
+| `contatos.exportacoes`       | `criar`, `listar`, `obter`, `baixar`, `baixar_fluxo`                                                                                                                                                 |
+| `segmentos`                  | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `topicos`                    | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `propriedades_contatos`      | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `modelos`                    | `criar`, `listar`, `obter`, `atualizar`, `remover`, `publicar`, `duplicar`, `prever`, `testar`, `obter_previa`                                                                                       |
+| `modelos.versoes`            | `listar`, `obter`, `restaurar`, `prever`                                                                                                                                                             |
+| `modelos.pastas`             | `listar`, `criar`, `atualizar`, `remover`                                                                                                                                                            |
+| `webhooks`                   | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `webhooks.eventos`           | `listar`, `obter`, `listar_tentativas`, `reenviar`                                                                                                                                                   |
+| `campanhas`                  | `criar`, `listar`, `obter`, `atualizar`, `remover`, `duplicar`, `revisar`, `enviar`, `cancelar`, `prever`, `ler_previa`, `testar`, `obter_metricas`, `listar_destinatarios`, `listar_links_clicados` |
+| `automacoes`                 | `criar`, `listar`, `obter`, `atualizar`, `remover`, `duplicar`, `parar`                                                                                                                              |
+| `automacoes.execucoes`       | `listar`, `obter`                                                                                                                                                                                    |
+| `eventos`                    | `criar`, `listar`, `obter`, `atualizar`, `remover`, `enviar`                                                                                                                                         |
+| `recebimento`                | `listar`, `obter`, `listar_anexos`, `obter_anexo`, `baixar_original`, `baixar_anexo`, `baixar_original_fluxo`, `baixar_anexo_fluxo`                                                                  |
+| `caixas`                     | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `caixas.etiquetas`           | `criar`, `listar`, `obter`, `atualizar`, `remover`                                                                                                                                                   |
+| `caixas.conversas`           | `listar`, `buscar`, `obter`, `atualizar`, `remover`                                                                                                                                                  |
+| `caixas.conversas.etiquetas` | `adicionar`, `substituir`, `remover`                                                                                                                                                                 |
+| `caixas.conversas.emails`    | `listar`, `obter`, `responder`, `encaminhar`                                                                                                                                                         |
+| `caixas.rascunhos`           | `criar`, `listar`, `obter`, `atualizar`, `remover`, `enviar`                                                                                                                                         |
+| `cli.concessoes`             | `listar`, `revogar`                                                                                                                                                                                  |
+
+`cli` é a classe agregadora que expõe `concessoes`, completando as 30 classes.
+A função local `Mailcore.verificar_assinatura` verifica webhooks sem fazer
+requisições HTTP e não integra a contagem dos 151 métodos.
+
+## Pedidos, respostas e paginação
+
+A gem mantém os nomes em português do contrato HTTP. Campos como
+`remetente`, `destinatarios`, `agendada_em`, `segmento_id` e `revisao` são enviados
+conforme fornecidos. O servidor valida regras de negócio, permissões e os DTOs
+específicos de cada recurso. A gem não converte um pedido de caixa em envio
+transacional nem acrescenta campos para ampliar permissões.
+
+JSON admite strings e símbolos como chaves, texto codificável em UTF-8, inteiros,
+floats finitos, booleanos, arrays, hashes e `nil`. Objetos arbitrários e números
+que seriam serializados como texto são recusados. Nomes de chave precisam
+permanecer únicos após a conversão para UTF-8. Respostas JSON usam chaves
+simbolizadas, preservando arrays e valores anuláveis.
+
+Omissão de um campo e seu envio explícito com `nil` têm significados diferentes.
+O transporte conserva `nil` e `false` no corpo; não aplica `compact`. Nos filtros
+da URL, `nil` é omitido e `false` permanece como `false`. Identificadores são
+codificados como um segmento de caminho; UUIDs, aliases, nomes de eventos e
+endereços de contato não viram trechos de URL controlados pela aplicação.
+
+A paginação é explícita. O cliente consulta uma página por chamada e devolve os
+cursores sem recalcular ou carregar páginas adicionais. O servidor pode aplicar
+limites diferentes por recurso; os envelopes permanecem próprios:
+
+| Envelope dentro de `resposta.dados`      | Grupos                                                                                                            |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `{ dados:, proximo: }`                   | E-mails, domínios e concessões CLI                                                                                |
+| `{ dados:, tem_mais:, proximo_cursor: }` | Contatos, exportações, segmentos, tópicos, propriedades de contatos, modelos/versões, webhooks/eventos/tentativas |
+| `{ dados:, proximo:, tem_mais: }`        | Campanhas e suas listas, automações/execuções, eventos personalizados, recebimento e caixas                       |
+| `{ dados: }`                             | Chaves de API, pastas de modelos e eventos de entrega de um e-mail                                                |
+
+## Contratos por área
+
+| Área                   | Regras relevantes                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Envio transacional     | Texto e/ou HTML, Cc/Cco, cabeçalhos e anexos CID conforme o DTO de composição. Até 50 destinatários somados, HTML + texto até 500 KiB, JSON do endpoint até 8 MiB, até 10 anexos com soma decodificada de 5 MiB nos tipos aceitos. A gem não baixa anexos remotos do envio transacional. Aceitação retorna `id` e `estado`; a entrega é acompanhada separadamente. |
+| Envio por modelo       | Modelo publicado por ID/alias e variáveis. Usa o DTO específico, com anexos básicos e sem compor simultaneamente conteúdo direto, Cc/Cco, cabeçalhos ou CID.                                                                                                                                                                                                       |
+| Lotes                  | Array de 1 a 100 mensagens, com aceitação atômica e ordenada. Sem anexos, Cc/Cco ou cabeçalhos de mensagem. Uma operação gera uma chamada; a gem não divide o lote ou repete automaticamente seu envio.                                                                                                                                                            |
+| Agendamento            | `agendada_em` usa ISO 8601 com fuso, dentro da janela de até 30 dias. Reagendar e cancelar dependem do estado atual e da autorização da chave.                                                                                                                                                                                                                     |
+| Domínios               | Capacidades de envio/recebimento `enabled` ou `disabled`, mantendo ao menos uma habilitada. Tracking e diagnóstico seguem os campos do servidor. Remover devolve o estado suspenso do domínio.                                                                                                                                                                     |
+| Chaves de API          | O segredo aparece somente na criação. A alteração pública renomeia a chave; a revogação devolve resposta sem conteúdo. A listagem não usa cursor.                                                                                                                                                                                                                  |
+| Contatos               | CRUD por UUID ou e-mail; associações exigem UUID. Nomes anuláveis, propriedades tipadas e preferências são preservados. Operações em lote admitem até 1.000 contatos. Tópicos usam as assinaturas `opt_in` e `opt_out`.                                                                                                                                            |
+| Importação de contatos | CSV UTF-8 em string JSON, até 8 MiB e 100.000 registros, com mapeamento por índice de coluna. O upload admite JSON até 50 MiB para acomodar os escapes. `prever` não persiste; `criar` inicia processamento e `obter` acompanha o estado. Não há método de listagem de importações.                                                                                |
+| Exportação de contatos | Criar com filtros, consultar/listar e baixar CSV. Criação e download revalidam o papel administrativo. `baixar` devolve bytes; `baixar_fluxo` entrega os blocos ao consumidor e devolve a contagem total.                                                                                                                                                          |
+| Modelos                | CRUD e publicação por UUID/alias, com revisão exigida na edição, publicação e restauração. Versões imutáveis, pastas hierárquicas, prévias e testes com destinatários explícitos. `obter_previa(organizacao_id, previa_id)` lê HTML pela rota autenticada.                                                                                                         |
+| Campanhas              | Marketing para segmento, tópico opcional, revisão e confirmação explícita no envio. Testes usam destinatários explícitos. Cancelamento respeita o estado da campanha; despacho concluído não comprova entrega. Métricas mantêm `nil` quando a telemetria está indisponível.                                                                                        |
+| Automações             | Fluxos ativos/inativos, etapas e conexões informadas juntas, condições, esperas, intervalos e ações do contrato. Parar impede novas inscrições e preserva as execuções aceitas. A gem consulta execuções; não oferece mutação individual dessas execuções.                                                                                                         |
+| Eventos personalizados | Definição com nome imutável e esquema opcional. Enviar ocorrência exige exatamente `email` ou `contato_id`, com `dados` até 64 KiB. Esquema `nil` difere de `{}`. O nome literal `send` continua consultável e editável pelos métodos de definição.                                                                                                                |
+| Webhooks               | CRUD, eventos, tentativas e reenvio do evento original. O servidor preserva identificador e payload no replay. Consumidores devem verificar a assinatura sobre o corpo bruto e deduplicar o `svix-id` antes de executar efeitos.                                                                                                                                   |
+| Recebimento            | Lista, busca, intervalo temporal e metadados/anexos. `obter` aceita `formato_html: 'cid'` ou `'data_uri'` no Hash de filtros; o formato efetivo pode ser `cid` por limite de expansão. Cabeçalhos repetidos permanecem pares ordenados. MIME original e anexos usam rotas fixas autenticadas.                                                                      |
+| Caixas                 | Caixas, etiquetas, conversas, mensagens e rascunhos usam IDs explícitos e revisões conforme o DTO. Responder e encaminhar aceitam a intenção de envio pela fila. Remover conversa a move para a lixeira. Etiquetas podem ser substituídas por `[]` para remover todas as associações.                                                                              |
+| Anexos de caixas       | Resposta/encaminhamento admitem Base64 ou URL e CID conforme o contrato; rascunhos recusam CID fornecido pelo cliente. O servidor resolve URLs com suas próprias proteções. O cliente Ruby não navega nessas URLs. JSON de caixas é limitado a 8 MiB no endpoint.                                                                                                  |
+| Concessões CLI         | Listagem e revogação das concessões autorizadas do ator atual. Fluxos interativos de autorização e renovação permanecem fora do cliente comum.                                                                                                                                                                                                                     |
+
+O teto de **50 MiB do transporte JSON** acomoda a importação escapada; ele não
+substitui limites menores de cada endpoint, como os 8 MiB do envio e das caixas.
+O limite padrão de leitura da resposta é **16 MiB**, configurável por operação.
+Downloads usam `String` binária. Os métodos com sufixo `_fluxo` exigem um bloco,
+leem de forma síncrona e mantêm o prazo e o teto de bytes durante o consumo.
+
+## Recebimento, Rails e limites de superfície
+
+O recurso `recebimento` acessa somente as rotas autenticadas de consulta, anexos,
+MIME original e download. URLs temporárias presentes nos metadados são
+capacidades sensíveis; a gem não as segue automaticamente e não envia a chave
+Mailcore a um endereço devolvido pela API. O conteúdo recebido está sujeito à
+retenção e à disponibilidade atuais do servidor. Listagem não garante que MIME
+ou anexos ainda estejam disponíveis.
+
+Rails é opcional. As integrações Action Mailer e Action Mailbox usam a mesma gem
+e o mesmo cliente HTTP; o cliente Ruby básico não exige carregar Rails. Templates
+Ruby/Rails podem produzir o HTML e o texto enviados ao Mailcore. A renderização
+React pertence à integração JavaScript e não faz parte desta gem.
+
+Esta matriz cobre os 151 métodos selecionados, sem anunciar toda a API do
+produto. As rotas públicas de métricas globais e auditoria existentes no backend
+ficam fora desta versão, assim como no SDK Node usado na conferência. Nenhum
+helper de dashboard, sessão, visualização compartilhada ou token temporário foi
+acrescentado por inferência. Endereços de anexos de caixas com prefixo de dashboard
+continuam como metadados; não há um método público fictício para baixá-los.
+
+O teste de contrato exercita os 151 métodos contra um transporte coletor,
+conferindo método, caminho, corpo, filtros, formato e opções. Os testes HTTPS
+reais com servidor sintético cobrem o transporte separadamente. Essa combinação
+não equivale a executar cada endpoint contra uma conta real ou a medir capacidade
+de envio em produção; os resultados efetivamente executados estão no relatório
+de verificação do repositório.

data/docs/integracao-api-interrupcao.json

@@ -0,0 +1,27 @@
+{
+  "data_utc": "2026-11-14T13:53:31.104091+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:149a81a02cb846ea058823aabc578bde130e86c93800e6335b2e89ed44e46d22",
+    "api_runtime": "sha256:158e95e9b87f2a126c038e6931b2f956fe6120f3566fd047a29250bd7783ff33",
+    "compilador": "sha256:8fa55b2f3ddf97471ab6a767bfa3f37e6bad0986ba823e75fea57e2a2a5c3073",
+    "postgres": "sha256:f1ea2a1a4fb7b68d4836be1fdcb8a6466a89b072158bf9d97663600538c294c5"
+  },
+  "backend_revisao": "52992028e5be8888db699d82e3cc8484140d6a67",
+  "backend_fontes_sha256": "d31c825268a64c858276827f47d27e506f543421327f487d7165e511359e248f",
+  "backend_fontes_alterados": false,
+  "api_compilada_neste_ensaio": true,
+  "falha": "Ensaio interrompido; recursos exclusivos serão removidos.",
+  "limpeza_concluida": true
+}

data/docs/integracao-api.json

@@ -0,0 +1,48 @@
+{
+  "data_utc": "2026-11-14T13:51:11.583482+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_inspect",
+    "envio_composto_idempotencia_409_download_cancelamento",
+    "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",
+    "cli_revogacao_e_limpeza_crud"
+  ],
+  "etapa": "concluido",
+  "imagens": {
+    "cliente": "sha256:1b334f043e1073752505db50e5d893d4c691a6d5478125ad5eee0038af2a2967",
+    "api_runtime": "sha256:158e95e9b87f2a126c038e6931b2f956fe6120f3566fd047a29250bd7783ff33",
+    "compilador": "sha256:8fa55b2f3ddf97471ab6a767bfa3f37e6bad0986ba823e75fea57e2a2a5c3073",
+    "postgres": "sha256:f1ea2a1a4fb7b68d4836be1fdcb8a6466a89b072158bf9d97663600538c294c5"
+  },
+  "backend_revisao": "83c2fa9859e03473e7af56eede97c6a1cad8592c",
+  "backend_fontes_sha256": "d31c825268a64c858276827f47d27e506f543421327f487d7165e511359e248f",
+  "backend_fontes_alterados": false,
+  "api_compilada_neste_ensaio": true,
+  "api_binario_sha256": "3cd977ab90dbfcc0067b7d0b85d120ae9132f4e873cc223298f901fc1dbd35bf",
+  "migracoes_aplicadas": 23,
+  "ruby": "3.4.12",
+  "recebimento_processado_por_worker": false,
+  "rails_real_exercitado": false,
+  "persistencia_sintetica": {
+    "mensagens": 3,
+    "tarefas_envio": 3,
+    "recebidos": 1,
+    "recebidos_pendentes": 1
+  },
+  "limpeza_concluida": true
+}