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!
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.
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:
minhaempresa
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.
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
Para indicar se sua requisição foi processada com sucesso ou não, o Konstati utiliza códigos de status HTTP.
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.
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
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.
GET
/account
Retorna informações sobre a sua conta no Konstati
Nenhum
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.
GET /v1/account { "username": "minhaempresa", "emailAddress": "email@example.com", "apiKey": "0e4fe7b1c0", "rateLimit": { "max": 10000, "reset": 1313389829, "current": 11, "usingSoftLimit": true } }
GET
/tests
Retorna uma lista de testes permitindo paginação e filtragem de resultados
type
Filtrar pelo tipo de teste realizado.
Possíveis valores:
Por enquanto o Konstati possui apenas o teste do SpamAssassin, mas assim que novos tipos de testes forem implementados, serão listados aqui.
pageSize
Quantidade de registros a serem retornados.
Possíveis valores são:
pageNumber
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.
lang
Filtrar pelo idioma
dos resultados dos testes.
customer
Filtar pelo cliente em nome do qual o teste foi realizado.
status
Filtrar por status
do teste.
Os valores permitidos neste campo estão descritos nesta seção da documentação.
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.
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
id
Para mais informações sobre os dados retornados, consulte o método POST
.
POST
/tests
Cria um novo teste no Konstati
type
Tipo do teste a ser realizado.
Possíveis valores são:
Teste antispam baseado nas regras do SpamAssassin. Por enquanto este é o único tipo de teste realizado pelo Konstati.
fromName
Nome do remetente.
fromEmail
Endereço de email do remetente.
É necessário especificar um endereço de email com formato válido.
subject
Assunto da mensagem.
bodyHtml
Corpo da mensagem em formato HTML.
replyToName
Nome do remetente no header Reply-To.
replyToEmail
Endereço de email do remetente no header Reply-To.
É necessário especificar um endereço de email com formato válido.
bodyText
Corpo da mensagem em formato Texto.
lang
Idioma no qual o resultado do teste será retornado.
Possíveis valores são:
customer
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.
id
emailMessage
Dados da mensagem:
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
error
Para testes assíncronos, existem mais dois possíveis valores:
processing
cancelled
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:
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
.
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" } ] } }
Para facilitar a implementação do Konstati em sua aplicação, criamos bibliotecas em três linguagens diferentes.
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.
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.
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.
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."
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.