Safety Optin 1.0

Instruções para Instalação do SafetyOptin versão 1.0

Introdução

O serviço Safety Optin caracteriza-se pela utilização de nossa API de integração em um formulário de inscrição já existente capaz de realizar as consultas de validação e verificação de emails no momento de uma inscrição eletrônica de qualquer pessoa para sua base de e-mails;

A validação pode filtrar os novos cadastros ou apenas informar o status de cada e-mail sem interferir no processo

Linguagem simples. Leve e amigável. O funcionamento é via JSON Instale em seu próprio formulário ou use um formulário automático da SafetyMails

Instalação

Etapa 1 Crie uma nova Aplicação

Para iniciar a integração serão necessárias as chaves de acesso, que podem se obtidas a partir do painel administrativo da SafetyMails, acessando o menu Safety Optin/Configurações

Existem duas maneiras de realizar a integração:

1. Integração via AJAX

2. Integração via "WebService"

Origem da consulta: numa integração via AJAX a origem da consulta consiste no endereço URL do formulário. Também é possível cadastrar apenas o domínio, assim todos as páginas que houverem formulário estarão incluídas.

Caso opte por cadastrar o endereço completo da página do formulário, apenas consultas oriundas deste endereço irão funcionar.

- Informe um nome para a aplicação.

- Digite a origem de onde virão as consultas de Safety Optin.

Etapa 2 Suas Chaves de Acesso

A ferramenta vai gerar suas chaves de acesso, com elas poderá realizar a autenticação na chamada, após criar sua aplicação terá acesso a API KEY e TICKET API referentes a aplicação em questão

Com estas informações poderá configurar seu script para realizar as consultas.

Etapa 3 Sintaxe da Consulta

O SafetyOptin consiste numa consulta via HTTP que retornará um JSON com o resultado da validação do e-mail desejado.

A Sintaxe da consulta:

https://optin.safetymails.com/main/ <COMANDO> / <API KEY> / <TICKET SITE> / <EMAIL CODIFICADO>

  • <COMANDO>: Parâmetro que informa o método utilizado na consulta
  • <API KEY>: Chave de acesso vinculada a sua conta da SafetyMails.
  • <TICKET API>: Chave de acesso vinculada a origem de consulta cadastrada.
  • <EMAIL CODIFICADO>: O e-mail deve ser codificado utilizando o protocolo “base64”, caso contrário o sistema não receberá com perfeição os dados.

Comandos disponívies

safetyoptin: realiza uma consulta via Javascript instalado em seu formulário, utilizando a url do formulário como forma de autenticação de origem

safetyRT: realiza a consulta via webService, utilizando o IP do solicitante como forma de autenticação de origem.

A integração é de fácil instalação e pode ser feita em diversas linguagens como Java Script, Phyton, C, PHP entre outras.

Etapa 4 Funcionamento da Validação

Após instalar a chamada para a consulta, pode utiliza-la para filtrar e-mails válidos em cadastros do seu site

Etapa 5 Sandbox

A integração oferece um ambiente de Sandbox para que possam ser feitos testes sem consumir seus créditos de uma consulta real.

Para utilizar a Sandbox basta mudar o comando da Sintaxe da URL de consulta como no exemplo abaixo:

http://optin.safetymails.com/main/sandbox/e6d796f06a51fe395a7b35421c779859ee6894fe/be9ef567a97b3d4c667dcd966fc2f5b690dbc366/+encodedEmail

O Sandbox apenas verifica se todos os retornos de status possíveis estão chegando corretamente em sua integração. Não são feitas validações reais.

Exemplos de Código

Exemplo 1 JavaScript
<meta charset='utf-8'>
<script src='https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js'></script> 
<label class='control-label'>E-mail</label>
<input type='text' name='Email' value='' class='email' />
<input type='submit' class="btn-teste" value='Validar E-mail'/>
<script>
	$(".btn-teste").click(function(){
		var a ="https://optin.safetymails.com/main/safetyoptin/e6d796f06a51fe395a7b35421c779859ee6894fe/be9ef567a97b3d4c667dcd966fc2f5b690dbc366/";
		$.get(a + btoa($(".email").val()), function(a, i) {
			alert("Este e-mail é "+a.StatusEmail);
		});
	});
</script>
Exemplo 2 PHP
<?php 
$apiKey = "e6d796f06a51fe395a7b35421c779859ee6894fe"; 
$tkSite = "be9ef567a97b3d4c667dcd966fc2f5b690dbc366"; 

$emailEncoded = base64_encode ("teste-safetyoptin@safetymails.com");

$return = file_get_contents("https://optin.safetymails.com/main/safetyRT/{$apiKey}/{$tkSite}/{$emailEncoded}");
$obj = json_decode($return);

print_r($obj);
Exemplo 3 Python
import urllib
import json
import base64

apiKey='e6d796f06a51fe395a7b35421c779859ee6894fe' #informado pela SafetyMails
ticketApi='be9ef567a97b3d4c667dcd966fc2f5b690dbc366' #informado pela SafetyMails

emailCodificado=base64.b64encode("teste-safetyoptin@algumlugar.com.br")

url="https://optin.safetymails.com/main/safetyRT/"+apiKey+"/"+ticketApi+"/"+emailCodificado

txt=json.loads(urllib.urlopen(url).read())

print txt

Retorno

O retorno da consulta é no formato JSON, e informará caso a consulta retorne algum tipo de erro.

  • IP/Dia: Informa o IP origem da consulta.
  • StatusCal: Status da chamada: OK ou Failed.
  • StatusEmail: Resultado da validação do e-mail, em caso de sucesso.
  • email: E-mail consultado.
  • public: Informa se o e-mail consultado é de domínio público ou privado.
  • referer: Informa a origem da consulta em caso de chamada via javascript.
  • MsgErro: Retorna a mensagem de erro referente a falha na chamada.
Exemplo de Retorno Sucesso
Object {
	IP/Dia:"192.168.2.2"
	StatusCal:"OK"
	StatusEmail:"INVALIDO"
	email:"teste-safetyoptin@safetymails.com"
	public:false
	referer:"https://www.safetymails.com"
}
Exemplo de Retorno Error
Object {
	IP/Dia:"192.168.2.2"
	StatusCal: "Failed",
	MsgErro : "Mensagem de erro"
	email:"teste-safetyoptin@safetymails.com"
	public:false
	referer:"https://www.safetymails.com"
}

Glossário

Status de E-mail

Válido - Endereço de e-mail cuja existência foi confirmada

Inválido - E-mail classificado como inexistente ou desativado em um domínio

Erro de Sintaxe - E-mail que não atende às regras de sintaxe estipuladas pelos provedores de e-mails e RFCs de mercado

Domínio Inválido - O domínio não existe ou apresentou falhas diversas

Scraped - E-mails inseridos nesta categoria podem representar ameaças diversas, inclusive de bloqueios. Os provedores admitem que estes e-mails foram criados a partir de serviços de scrapers (daí seu nome), que são geradores automáticos de endereços "contato, adm, vendas, etc" para diversos domínios, caracterizando spam. Também podem ser e-mails de callcenters ou outros que não possuam um indivíduo responsável

Pendente - E-mails dos quais ainda não possuímos informações em nosso banco de dados. Após um período de nova análise, específica para estes endereços, podemos ainda não possuir todas as informações. Estes e-mails têm seus créditos estornados para sua conta.

Incerto - Também são conhecidos como "Accept All" e "Deny All". Ou seja, recebem todas as mensagens ou negam todas as mensagens, independentemente de seu conteúdo. O resultado não pode ser confirmado.

Descartável - E-mails provenientes de serviços de endereços temporários. Eles são válidos, mas apenas por algum tempo (horas ou minutos). Após este período, tornam-se inválidos e prejudicam sua entregabilidade.

Desconhecido - E-mails cujos servidores são configurados para não fornecer quaisquer informações de seus usuários. Desta forma, não é possível obter confirmações que os identifiquem. Ocorre mais em e-mails corporativos.

Junk - Estes são endereços de e-mail cuja sintaxa não os invalida, mas possuem elementos que serão identificados pelos provedores e direcionados para pasta junk, lixo eletrônico ou spam. E-mails com caracteres repetidos, palavrões, sequências numéricas e etc.

Limitado - Endereços de e-mails que, sabidamente, possuem regras de filtragem de mensagens por volume e poderão causar problemas na entrega, como bloqueios.

Mensagens de Erro

Sintaxe incorreta! Entre em contato com o Suporte
Há um erro de sintaxe na url da chamada, verifique o tópico de sintaxe, aqui

Acesso ao safetyCheck de um IP Inválido [%s]<>[%s]
Um IP diferente do cadastrado para consultas pelo comando 'SafetyCheck'

Excedido o limite de consultas do IP %s (%s)<>(%s)
Para consultas com comando 'SafetyOptin' via JavaScript há um limite de tentativas/dia pelo mesmo IP de usuário, padrão: 20

HTTP Erros

HTTP CODE 422 Referer ou ApiKey Inválidos

HTTP CODE 423 Acesso ao SafetyOptin de um Referer Inativo %

HTTP CODE 424 Acesso por um SafetyOptin Inativo

HTTP CODE 427 Sem créditos para realizar a pesquisa