Teste Antispam para Templates de Email marketing

A API do Konstati já está disponível!

Através da API, você poderá integrar a funcionalidade do Konstati em sua aplicação sem que o usuário acesse outra interface.

Consulte as condições entrando em contato consoco!

Introdução

A API do Konstati foi desenvolvida para ser simples e funcional. Trata-se de um serviço REST, onde os tipos de operações são determinados pelo método HTTP utilizado na requisição (GET, POST, PUT e DELETE), as respostas do servidor são enviadas no formato JSON e a autenticação é HTTP Basic.

Autenticação

O Konstati é um serviço que requer autenticação para acesso à todas as suas funcionalidades, e o método utilizado é o HTTP Basic. O endereço base da API é:

https://api.konstati.com/v1

Obs.: v1 indica a versão da API.

Ao cadastrar-se no Konstati você receberá um usuário e uma chave de acesso para a API.

A partir de agora, vamos usar os seguintes dados nos nossos exemplos:

usuário: minhaempresa
chave de acesso: 0e4fe7b1c0

Seguindo o padrão de autenticação HTTP Basic, em cada requisição é preciso enviar o usuário e chave de acesso separados por : e convertidos para base64 e um cabeçalho adicional (Authorization).

Veja o exemplo:

Nesse caso, convertendo minhaempresa:0e4fe7b1c0 em base64 e colocando no cabeçalho temos:

Authorization: Basic bWluaGFlbXByZXNhOjBlNGZlN2IxYzA=

Para testar a autenticação você pode fazer uma requisição GET direto pelo navegador. Para obter informações sobre sua conta, basta acessar https://api.konstati.co/v1/account. Informe seu usuário e chave de acesso e você deverá ver algo parecido com:

{
    "username": "minhaempresa",
    "emailAddress": "email@example.com",
    "apiKey": "0e4fe7b1c0",
    "rateLimit": {
        "max": 10000,
        "reset": 1313389829,
        "current": 11
    }
}

Você também pode usar uma ferramenta como cURL para testar direto de sua linha de comando:

$ curl -v -u 'minhaempresa:0e4fe7b1c0' https://api.konstati.com/v1/account

A requisição feita será algo parecido com:

> GET /v1/account HTTP/1.1
> Authorization: Basic a29uc3RhdGk6a29uc3RhdGk=
> User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: api.konstati.co
> Accept: */*

E a resposta do nosso servidor:

< HTTP/1.1 200 OK
< Server: nginx/0.8.54
< Date: Fri, 15 Jul 2011 10:20:35 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Connection: keep-alive
<
{
    "username": "minhaempresa",
    "emailAddress": "email@example.com",
    "apiKey": "0e4fe7b1c0",
    "rateLimit": {
        "max": 10000,
        "reset": 1313389829,
        "current": 11
    }
}

Ao desenvolver sua aplicação você provavelmente irá utilizar bibliotecas que facilitam o envio de requisições HTTP com autenticação.

Formato de Dados

O Konstati usa JSON como seu único formato para entrada e saída de dados.

Em requisições POST e PUT não esqueça de especificar o cabeçalho Content-Type:

Content-Type: application/json

Já em requisições GET os parâmetros são passados via query string, como no exemplo abaixo:

https://api.konstati.com/v1/tests?perPage=20&pageNumber=1

Códigos de Resposta

Para indicar se sua requisição foi processada com sucesso ou não, o Konstati utiliza códigos de status HTTP.

Sucesso

200 OK: Retornado para requisições GET e PUT.
201 Created: Retornado para requisições POST, indicando que o elemento foi criado com sucesso.
202 Accepted: Retornado para requisições POST, indicando que a requisição foi aceita, mas não foi processada ainda. Esse é o caso dos testes assíncronos.
204 No Content: Retornado para requisições DELETE, indicando que o elemento foi removido com sucesso.

Erro

400 Bad Request

Há um erro nos parâmetros informados na requisição. Mais informações sobre o erro estão no corpo da resposta. Exemplo:

{"errorMessage": "Field 'subject' is required"}

401 Unauthorized

Tentativa de acesso com credenciais incorretas.

404 Not Found

O elemento acessado não foi encontrado.

500 Internal Server Error

Ocorreu algum erro no Konstati e nós já fomos avisados =P

Tipos de Testes

No Konstati, os testes são classificados de acordo com o momento em que o resultado é disponibilizado.

Testes síncronos são aqueles em que o resultado é retornado para a requisição que solicitou o teste. Já os testes assíncronos retornarão apenas a informação de que a requisição foi recebida e que está sendo processada.

No momento o único tipo de teste disponível no Konstati é o do SpamAssassin, que é síncrono.

Endpoints

account

GET /account Retorna informações sobre a sua conta no Konstati

Parâmetros

Nenhum

Valores retornados

username

Seu nome de usuário.

emailAddress

Endereço de email cadastrado em sua conta.

apiKey

Chave de acesso da API (a mesma que você usou para acessar esse serviço =P).

rateLimit

Informações sobre os limites definidos para sua conta.

max: Quantidade de testes permitida pelo plano contratado.
reset: Segundos até que a contagem de testes executados seja reiniciada.
current: Testes executados durante o período atual de cobrança.
usingSoftLimit: Indica se sua conta permite que o limite de testes mensal seja ultrapassado, para que os testes adicionais sejam cobrados na fatura seguinte. Para mais informações entre em contato conosco.

Exemplo

GET /v1/account
{
    "username": "minhaempresa",
    "emailAddress": "email@example.com",
    "apiKey": "0e4fe7b1c0",
    "rateLimit": {
        "max": 10000,
        "reset": 1313389829,
        "current": 11,
        "usingSoftLimit": true
    }
}

tests

GET /tests Retorna uma lista de testes permitindo paginação e filtragem de resultados

Parâmetros

opcionaltype

Filtrar pelo tipo de teste realizado.

Possíveis valores:

spamassassin

Por enquanto o Konstati possui apenas o teste do SpamAssassin, mas assim que novos tipos de testes forem implementados, serão listados aqui.

opcionalpageSize

Quantidade de registros a serem retornados.

Possíveis valores são:

padrão 20
mínimo 20
máximo 100

opcionalpageNumber

Número da página a ser retornada.

Se o número da página soliticada for maior do que o número de páginas disponíveis, será retornado um erro 404 Not Found.

Para facilitar o uso do sistema de paginação, ao solicitar uma lista de testes são retornados campos que indicam a URL da próxima página e da página anterior.

opcionallang

Filtrar pelo idioma dos resultados dos testes.

opcionalcustomer

Filtar pelo cliente em nome do qual o teste foi realizado.

opcionalstatus

Filtrar por status do teste.

Os valores permitidos neste campo estão descritos nesta seção da documentação.

Valores retornados

pageNumber

Número da página retornada.

start

Número do primeiro registro retornado.

end

Número do último registro retornado.

totalCount

Quantidade total de registros (soma de todas as páginas).

nextPage

URL relativa ao endereço base da API representando a página seguinte.

Se a página atual for a última, o valor deste campo será null.

previousPage

URL relativa ao endereço base da API representando a página anterior.

Se a página atual for a primeira, o valor deste campo será null.

tests

Lista dos testes encontrados.

Os valores retornados para cada teste estão descritos nesta seção da documentação.

Exemplo de Resposta

GET /v1/tests?pageNumber=1&pageSize=20&customer=ppadron

{
  "pageNumber": 1,
  "start": 1,
  "end": 20,
  "pageSize": 20,
  "totalCount": 61,
  "nextPage": "/v1/tests?pageNumber=2&pageSize=20&customer=ppadron",
  "previousPage": null,
  "tests": [
    {
      "id": "4e1f323377e646c14500000d"
      ...
    },
    {
      "id": "4e1f329777e646c64500000e"
      ...
    },
    ...
  ]
}

GET /tests/{id} Retorna os dados de um teste específico

Parâmetros

POST /tests Cria um novo teste no Konstati

Parâmetros

obrigatóriotype

Tipo do teste a ser realizado.

Possíveis valores são:

spamassassin: Teste antispam baseado nas regras do SpamAssassin. Por enquanto este é o único tipo de teste realizado pelo Konstati.

obrigatóriofromName

Nome do remetente.

obrigatóriofromEmail

Endereço de email do remetente.

É necessário especificar um endereço de email com formato válido.

obrigatóriosubject

Assunto da mensagem.

obrigatóriobodyHtml

Corpo da mensagem em formato HTML.

opcionalreplyToName

Nome do remetente no header Reply-To.

opcionalreplyToEmail

Endereço de email do remetente no header Reply-To.

É necessário especificar um endereço de email com formato válido.

opcionalbodyText

Corpo da mensagem em formato Texto.

opcionallang

Idioma no qual o resultado do teste será retornado.

Possíveis valores são:

padrão pt

opcionalcustomer

Nome/login do cliente para o qual o teste será realizado.

Este campo é útil caso você queira integrar o Konstati em uma aplicação com controle de usuários, como uma plataforma de envio de email marketing. Ao invés de manter o controle dos testes em sua aplicação, basta utilizar este campo para identificar seu cliente.

Através do comando GET /tests?customer=name você pode obter uma lista de todos os testes do cliente name.

Valores retornados

id

ID do teste criado.

emailMessage

Dados da mensagem:

fromName
fromEmail
subject
bodyHtml
bodyText

customer

Nome/login do cliente para o qual o teste foi realizado.

lang

Idioma do resultado do teste.

type

Tipo do teste realizado.

status

Status do teste.

Para testes síncronos, os possíveis valores são:

done: Teste concluído com sucesso.
error: Ocorreu um erro durante o processamento do teste.

Para testes assíncronos, existem mais dois possíveis valores:

processing: Teste ainda está sendo processado.
cancelled: Teste foi cancelado pelo usuário.

startedAt

Momento em que o teste foi iniciado (segundos).

updatedAt

Momento em que ocorreu a última atualização de status do teste.

totalRuntime

Tempo que o teste levou para ser processado.

result

Resultado do teste. A estrutura deste elemento depende do tipo de teste realizado:

SpamAssassin

isSpam

Se o score for maior que 5, a mensagem será identificada como spam.

score

Soma da pontuação de todas as regras atingidas.

matchedRules

Conjunto de regras atingidas pela mensagem.

Cada regra possui os seguintes campos:

score

Pontuação individual da regra.

ruleName

Identificador da regra.

Descrição da regra no idioma solicitado.

tips

Campo de texto com dicas de como evitar que essa regra seja infringida pela mensagem.

Este campo não está disponível para todas as regras, portanto seu valor pode ser null.

Exemplo

POST /tests
{
  "type": "spamassassin",
  "fromName": "John Doe",
  "fromEmail": "john@example.com",
  "bodyHtml": "html content",
  "subject": "Message Subject",
  "lang": "pt"
}

{
  "id": "4e1f339677e646bf4500000f",
  "emailMessage": {
      "fromName": "John Doe",
      "fromEmail": "john@example.com",
      "bodyHtml": "html content",
      "bodyText": null,
      "subject": "Message Subject"
  },
  "customer": "ppadron",
  "lang": "pt",
  "type": "spamassassin",
  "status": "done",
  "startedAt": 1310667670.106,
  "updatedAt": 1310667670.148,
  "totalRuntime": 0.04190993309021,
  "result": {
    "isSpam": false,
    "score": 1.7,
    "matchedRules": [
      {
        "score": 0.001,
        "ruleName": "HTML_MESSAGE",
        "description": "Mensagem possui HTML",
        "tips": null
      },
      {
        "score": 0.635,
        "ruleName": "HTML_MIME_NO_HTML_TAG",
        "description": "Mensagem é HTML mas não possui a tag <html>",
        "tips": null
      },
      {
        "score": 1.105,
        "ruleName": "MIME_HTML_ONLY",
        "description": "Mensagem possui somente a versão HTML",
        "tips": "Considere utilizar também uma versão texto para seu email"
      }
    ]
  }
}

Bibliotecas

Para facilitar a implementação do Konstati em sua aplicação, criamos bibliotecas em três linguagens diferentes.

PHP

A biblioteca do Konstati em PHP está disponível como um pacote PEAR e pode ser instalada com os comandos:

$ pear channel-discover pear.w3p.com.br
$ pear install w3pear/Konstati

Ou, se preferir pode fazer o download direto do repositório do Github.

Apenas certifique-se de que o include_path contém o diretório onde a biblioteca foi instalada.

Exemplos

Descobrindo quantos testes ainda estão disponíveis no mês:

require_once 'Konstati.php';

$konstati    = new Konstati('minhaempresa', '0e4fe7b1c0');
$accountInfo = $konstati->account->getInfo();

$availableTests = $accountInfo->rateLimit->max - $accountInfo->rateLimit->current;
$resetDate      = date('d/m/Y', $accountInfo->rateLimit->reset);

echo "Minha empresa possui {$availableTests} disponíveis até o dia {$resetDate}.";

Realizando um teste com o SpamAssassin:

$test = $konstati->tests->create(array(
    'type'      => 'spamassassin',
    'subject'   => 'Minha Mensagem de Teste',
    'fromName'  => 'John Doe',
    'fromEmail' => 'john@example.com',
    'bodyHtml'  => '<h1>SPAM</h1>'
));

echo "Esta mensagem atingiu {$test->result->score} pontos no SpamAssassin.";

Todos os nomes de parâmetros e atributos seguem o padrão descrito anteriormente neste documento.

Ruby

A biblioteca do Konstati em Ruby está disponível como gem e pode ser instalada com o comando rubygems:

$ gem install konstati

Ou, se preferir pode fazer o download direto do repositório do Github.

Exemplos

Descobrindo quantos testes ainda estão disponíveis no mês:

require 'konstati'

Konstati.username = ''
Konstati.apikey   = ''

info = Konstati::Account.info

puts "I still have #{info['rateLimit']['credits']} credits left."

Realizando um teste com o SpamAssassin:

require 'konstati'

Konstati.username = ''
Konstati.apikey   = ''

test = Konstati::Tests.create(
  :type      => "spamassassin",
  :bodyHtml  => "<p>Hello World</p>",
  :bodyText  => "Hello World",
  :subject   => "CHEAP PILLS!!!!",
  :fromEmail => "john@example.com",
  :fromName  => "John Doe",
)

puts "This email has scored #{test['result']['score']} points in SpamAssassin."

Termos de Uso

Os dados preenchidos no formulário de teste não serão armazenados pelo Konstati. Serão armazenados apenas os resultados dos testes (pontuação e regras aplicadas) para fins estatísticos.

Os resultados do teste antispam não são totalmente precisos, uma vez que nem todos os servidores de email usam o SpamAssassin para testes antispam e, aqueles que o utilizam, podem alterar a pontuação de cada regra para o valor que melhor lhe convierem, bem como podem acrescentar novas regras personalizadas, que não são de conhecimento público.

Algumas regras do SpamAssassin não estão disponíveis no Konstati, pois avaliam itens que fogem do escopo desta ferramenta, como a reputação de servidores de envio, SPF e DKIM. Futuramente, o Konstati disponibilizará testes também para esses itens.