mailcore

# SDK Mailcore para Elixir

[Código-fonte](https://github.com/mailcore-hq/mailcore-elixir) · [Problemas e sugestões](https://github.com/mailcore-hq/mailcore-elixir/issues)

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:

```elixir
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:

```elixir
{: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:

```bash
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.

```elixir
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](exemplos/phoenix/README.md) 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](docs/cobertura.md) 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](docs/uso.md) 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.