meeng_sdk (Elixir)

SDK do Meeng.dev para Elixir 1.18 ou mais novo: e-mails, domínios, contatos, listas de contatos, campanhas, analytics e webhooks. Sem dependências além da biblioteca padrão (:httpc e o módulo JSON).

Gerado pelo sdk/generator a partir do contrato da API do Meeng.dev (versão 1.0.0); não edite à mão.

Começando

client = Meeng.new("mg_123")

{:ok, sent} =
  Meeng.Emails.send(client, %{
    from: "contato@acme.com.br",
    to: "ana@example.com",
    subject: "Olá",
    html: "<p>Olá!</p>"
  })

sent["emailId"]

Toda chamada devolve {:ok, dados} ou {:error, %Meeng.Error{}} (com status, code, como NOT_UNIQUE ou FORBIDDEN, message e retry_after). Os corpos são mapas (ou listas de palavras-chave) com as chaves da API, em camelCase (contactBookId), e os dados são o JSON da resposta decodificado em mapas com chaves de texto.

Meeng.new/2 lê a chave de MEENG_API_KEY e o endereço do app de MEENG_BASE_URL quando não os recebe. A opção :base_url é o endereço do app (para instalações próprias), sem /api/v1; ele precisa ser https, e http só vale para localhost, 127.0.0.0/8 e ::1, para a chave nunca viajar em texto puro. O transporte padrão usa :httpc e não segue redirecionamentos.

Recursos

Meeng.Emails

Meeng.Domains

Meeng.Contacts

Meeng.ContactBooks

Meeng.Campaigns

Meeng.Analytics

Meeng.Emails.create/3 é outro nome de send/3, e Meeng.Campaigns.get_all/2 de list/2.

Os filtros de listagem são opções em snake_case (start_date:, domain_id:); uma lista em domain_id vira um domainId por valor. Meeng.Emails.send/3 e batch/3 aceitam idempotency_key: "pedido-1": a mesma chave com o mesmo corpo devolve o primeiro resultado.

O Meeng.dev não anexa, não guarda e não repassa arquivos, e por isso nenhum SDK tem o campo attachments. Hospede o arquivo onde preferir (seu armazenamento, um link assinado com prazo) e ponha o link no corpo do e-mail:

<p>Sua fatura está pronta: <a href="https://exemplo.com.br/faturas/1042?token=...">baixar a fatura (PDF)</a></p>

Se um pedido chegar à API com attachments e itens, ela responde 400 (ZodError) com a mensagem Attachments are not supported. Include links to your files in the email body.; uma lista vazia passa. Para um documento sensível, use um link que expira.

Configuração

A API do Meeng.dev fica em https://meeng.dev/api. O cliente recebe o endereço do app, https://meeng.dev (o padrão), e acrescenta /api/v1 a cada chamada. Crie uma chave em Configurações > Chaves; ela tem a forma mg_<id>_<segredo>.

meeng =
  Meeng.new("mg_...",
    base_url: "https://meeng.dev",
    timeout: 10_000,
    max_retries: 3,
    retry_delay: 1_000
  )

Exemplos

A pasta examples/ tem programas que rodam: enviar um e-mail, enviar em lote, agendar (remarcar e cancelar), adicionar um domínio (com os registros DNS) e verificar um webhook.

Exemplo Arquivo Rode com
Enviar um e-mail examples/send_email.exs mix run examples/send_email.exs
Enviar em lote examples/send_batch.exs mix run examples/send_batch.exs
Agendar, remarcar e cancelar examples/schedule_email.exs mix run examples/schedule_email.exs
Adicionar um domínio examples/add_domain.exs mix run examples/add_domain.exs
Verificar um webhook examples/verify_webhook.exs mix run examples/verify_webhook.exs

Todos leem MEENG_API_KEY e, se quiser apontar para outro app, MEENG_BASE_URL; o de webhook roda sem chave, com uma requisição montada no próprio programa.

Paginação

As listagens de e-mails, contatos e campanhas são paginadas por page (a partir de 1) e, nas duas primeiras, limit. emails.list devolve count, o total de e-mails; campaigns.list devolve totalPage, o total de páginas; contacts.list devolve a lista sem total, e a última página é a que vem com menos de limit contatos.

defmodule Emails do
  # Todas as páginas de e-mails, de 100 em 100.
  def todos(meeng, page \\ 1, acumulado \\ []) do
    {:ok, %{"data" => data, "count" => count}} = Meeng.Emails.list(meeng, page: page, limit: 100)
    acumulado = acumulado ++ data

    if length(acumulado) >= count or data == [],
      do: acumulado,
      else: todos(meeng, page + 1, acumulado)
  end
end

Erros

Uma recusa da API é {:error, %Meeng.Error{}}, com status, code, message e retry_after; uma falha de rede tem o código "transport":

case Meeng.Emails.get(meeng, "em_123") do
  {:ok, email} -> email
  {:error, %Meeng.Error{code: "NOT_FOUND"}} -> nil
  {:error, error} -> raise error
end

Os códigos que a API devolve: UNAUTHORIZED (sem chave), FORBIDDEN (chave inválida ou sem permissão), NOT_FOUND, NOT_UNIQUE (a mesma chave de idempotência com outro corpo, ou ainda em andamento), RATE_LIMITED, BAD_REQUEST, METHOD_NOT_ALLOWED, NOT_IMPLEMENTED e INTERNAL_SERVER_ERROR. Uma validação recusada vira o código ZodError, e a mensagem é a primeira falha (from: Required).

Tentativas automáticas

O cliente repete sozinho a chamada que pode ser repetida, até :max_retries vezes depois da primeira tentativa (2 por padrão; 0 envia cada chamada uma vez só):

Resposta Repete?
429 (limite de requisições por segundo) Sempre: a chamada não foi processada, então qualquer uma pode ser repetida.
500, 502, 503, 504 ou falha de conexão Só quando repetir não faz o trabalho duas vezes: uma leitura (GET), um PUT, um DELETE, ou uma chamada com chave de idempotência. Um envio sem chave não é repetido.
409 e qualquer outra recusa Nunca.

A primeira repetição espera :retry_delay (em milissegundos) (500 ms por padrão), cada uma seguinte espera o dobro, até 30 segundos, e o Retry-After que a API devolve vale no lugar dessa espera. Esgotadas as tentativas, a última resposta é o erro.

Webhooks

# headers: uma lista ou mapa de pares; body: o corpo cru, antes de interpretá-lo.
case Meeng.Webhooks.construct_event("whsec_xxx", headers, body) do
  {:ok, %{"type" => "email.delivered", "data" => data}} -> data["to"]
  {:ok, _outro_evento} -> :ok
  {:error, %Meeng.WebhookVerificationError{wire_code: code}} -> {:refused, code}
end

Meeng.Webhooks.verify/4 só confere a assinatura e devolve true ou false. construct_event/4 confere e devolve o evento, ou {:error, %Meeng.WebhookVerificationError{}} com wire_code: MISSING_SIGNATURE, MISSING_TIMESTAMP, INVALID_SIGNATURE_FORMAT, INVALID_TIMESTAMP, TIMESTAMP_OUT_OF_RANGE, SIGNATURE_MISMATCH ou INVALID_JSON.

A assinatura é v1= mais o HMAC-SHA256, em hexadecimal, de {timestamp}.{corpo} com o segredo do webhook; o timestamp vem em milissegundos. A tolerância padrão é de 5 minutos (tolerance:, em milissegundos; um número negativo desliga a checagem). Os cabeçalhos são X-Meeng-Signature, X-Meeng-Timestamp, X-Meeng-Event e X-Meeng-Call.

Eventos: contact.created, contact.updated, contact.deleted, domain.created, domain.verified, domain.updated, domain.deleted, email.queued, email.sent, email.delivery_delayed, email.delivered, email.rejected, email.rendering_failure, email.complained, email.cancelled, email.bounced, email.clicked, email.failed, email.opened, email.suppressed, webhook.test.

Desenvolvimento

mix compile --warnings-as-errors
mix test --warnings-as-errors

O ./check.sh da raiz do repositório sobe uma API de mentira gerada do contrato (go run ./cmd/fakeapi), que recusa o que o contrato não permite, e roda contra ela o teste de contrato (cada método do SDK é chamado, e nenhuma operação pode ficar de fora) e os exemplos.