SDK Mailcore para Elixir

Código-fonte · Problemas e sugestões

Cliente da API Mailcore para Elixir 1.16+ e Erlang/OTP 26+, com 151 operações organizadas em 30 módulos de recursos. Use mapas para os pedidos e receba tuplas {:ok, resposta} ou {:error, erro}. A aplicação OTP gerencia o transporte compartilhado; o cliente é um valor imutável que pode ser usado por processos concorrentes.

Versão 0.1.0-alpha.1, aplicação e pacote :mailcore. O ambiente Docker serve para desenvolver e verificar a biblioteca; aplicações consumidoras usam suas ferramentas Elixir habituais.

Instalação

Para versões disponíveis no Hex, acrescente a dependência em mix.exs da aplicação consumidora:

defp deps do
  [
    {:mailcore, "0.1.0-alpha.1"}
  ]
end

Execute mix deps.get na aplicação consumidora.

Desenvolvimento e instalação local

Para usar este checkout durante o desenvolvimento, substitua a dependência por uma referência local:

{:mailcore, path: "../mailcore-elixir"}

O caminho considera a aplicação e o checkout mailcore-elixir no mesmo diretório pai; ajuste-o à organização do seu projeto. Execute mix deps.get na aplicação consumidora. A verificação de distribuição também instala o pacote gerado num consumidor separado do checkout.

Para desenvolver e executar os testes dentro de Docker:

docker build -t mailcore/elixir-testes:1.16 .
docker run --rm --network none --read-only \
  --tmpfs /tmp:rw,exec,nosuid,size=512m \
  --tmpfs /sdk/_build/test/lib/mailcore/.mix:rw,nosuid,size=32m \
  mailcore/elixir-testes:1.16

O build resolve as dependências de desenvolvimento no contêiner. Os testes sintéticos executam sem rede externa, sem publicar portas e sem instalar Elixir ou Erlang no host. Os diretórios temporários permitem os arquivos de execução e o manifesto do ExUnit. A matriz usa Elixir/OTP 1.16/26, 1.17/27, 1.18/27, 1.19/28 e 1.20/29.

Enviar o primeiro e-mail

Configure MAILCORE_API_KEY no ambiente protegido da aplicação. Use um remetente com domínio verificado e uma chave com permissão de envio.

alias Mailcore.Recursos.Emails

cliente = Mailcore.cliente()

pedido = %{
  remetente: "notificacoes@seudominio.com.br",
  destinatarios: ["cliente@example.com"],
  assunto: "Pedido recebido",
  html: "<p>Recebemos seu pedido.</p>",
  texto: "Recebemos seu pedido."
}

case Emails.enviar(cliente, pedido, chave_idempotencia: "pedido-123-confirmacao") do
  {:ok, resposta} ->
    dados = Mailcore.Resposta.json!(resposta)
    IO.puts(dados["id"])

  {:error, erro} ->
    # Classifique erro.codigo e erro.status sem registrar a mensagem privada da API.
    IO.puts(Exception.message(erro))
end

Uma aceitação HTTP 202 registra a intenção. Os eventos e webhooks acompanham o resultado da entrega. Persista a chave de idempotência e o conteúdo da intenção para decidir com segurança se uma repetição é necessária.

Swoosh e Phoenix

O adaptador opcional Mailcore.Adaptadores.Swoosh integra mailers Swoosh, inclusive em aplicações Phoenix. Configure uma chave de idempotência estável em provider_options de cada mensagem. deliver_many/2 envia individualmente e interrompe na primeira falha; a operação atômica de lote pertence a Mailcore.Recursos.Lotes.

O exemplo Phoenix reúne mailer, controller e configuração, com mensagens sintéticas nos testes. A biblioteca base também pode ser usada sem Swoosh.

Recursos e respostas

Os módulos de Mailcore.Recursos incluem Emails, Lotes, Dominios, ChavesApi, Contatos, Segmentos, Topicos, PropriedadesContatos, Modelos, Webhooks, Campanhas, Automacoes, Eventos, Recebimento, Caixas e os recursos subordinados. Todos recebem cliente como primeiro argumento e opções por chamada no último argumento. Consulte a cobertura para os 30 módulos e 151 operações.

%Mailcore.Resposta{} conserva status, cabecalhos, dados e total_bytes. dados é o binário original. Mailcore.Resposta.json/1 retorna uma tupla com o conteúdo decodificado; json!/1 levanta erro sanitizado quando o conteúdo não é JSON válido. Chaves decodificadas permanecem strings. Decimais usam %Decimal{}; o parser Jason admite inteiros com até 1.024 dígitos, preservando os bytes originais para outros tratamentos.

%Mailcore.Erro{} oferece codigo, mensagem, status opcional e cabecalhos. O campo mensagem pode conter dados privados retornados pela API. Exception.message/1 e a representação padrão omitem essa mensagem de negócio. Configuração inválida ao criar o cliente levanta Mailcore.Erro; operações retornam a tupla de erro.

As variantes de download terminadas em _fluxo entregam blocos ao consumidor, sem acumular o arquivo na resposta. O consumidor retorna :ok ou {:error, %Mailcore.Erro{}}. Sucesso mantém dados: "" e informa total_bytes.

O transporte padrão usa Req/Finch com opções próprias, TLS verificado e pool HTTP/1.1 compartilhado. A execução é independente de Req.default_options, sem retentativas, redirecionamentos, cookies ou transformação automática dos bytes. Um Req injetado permanece sob as políticas da aplicação.

O guia de uso detalha configuração, paginação, modelos, lotes, opções, downloads e webhooks. O contrato de negócio permanece validado pelo servidor. Os ensaios locais não medem capacidade de entrega SMTP nem desempenho em produção.