APIs do Email Marketing

De Wiki Locaweb
Ir para: navegação, pesquisa

Índice

Introdução

As APIs de integração do Email Marketing permitem que você integre sua base de contatos com a base da ferramenta, mantendo-as sincronizadas, além de possibilidade o envio e agendamento de mensagens.

Para utilizá-las, é necessário ter conhecimento de linguagens de programação. Não há restrição quanto à linguagem utilizada, uma vez que isso pode ser escolha do desenvolvedor, e as APIs utilizam o padrão REST, que facilita a interoperabilidade.


Padrão Utilizado

Os webservices do Email Marketing utilizam o padrão REST e o formato JSON codificado em UTF-8 para expor os recursos disponíveis.

Notação utilizada nesta página

Cada conta possui parâmetros diferentes que devem ser utilizados na chamada dos Webservices.
Nesta documentação, representamos essa variáveis pela tag [], por exemplo [HOSTNAME]
Para que a URL funcione, é necessário substituir essas tags pelo valor real, que pode ser obtido na página de Configurações do Email Marketing como na figura abaixo:

link=‎

Este é um exemplo de chamada de listagem de contatos válidos, o padrão é:

http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/contatos/validos/?chave=[CHAVE]&pagina=1 

Então a URL a ser utilizada para listar os contatos válidos será:

http://emailmkt11.locaweb.com.br/admin/api/demo_lmm/contatos/validos/?chave=1f0d3ddf77594709903087bc134bc624b&pagina=1

Como testar requisições POST

Para os webservices que são acessíveis via POST, como o webservice de importação de contatos por exemplo, aconselhamos a utilização de alguma das ferramentas abaixo para simular o post:

Códigos HTTP de retorno

Os webservices do EmailMarketing retornam códigos de erro HTTP abaixo seguidos de uma mensagem de erro:

Codigo Descrição
200 Sucesso
400 Parâmetros inválidos
404 Não Encontrado
401 Não autenticado
403 Não autorizado
409 Conflito
413 Tamanho do corpo da requisição é maior que o esperado
500 Erro interno no servidor

Recursos

Contatos


Exportar

GET http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/contatos/[STATUS]/?chave=[CHAVE]&pagina=[PAGINA]&lista=[ID_LISTA]

[STATUS] = "validos", "invalidos", "descadastrados" ou "nao_confirmados"
[PAGINA] = número da pagina que deve ser retornada
[ID_LISTA] = id de alguma lista que pode ser obtido na página de Listas do Emailmkt (parâmetro opcional)

obs: atualmente o limite de contatos por página é de 10mil contatos por página.
Por isso, caso tenha 15mil contatos em sua base por exemplo, precisará fazer 2 chamadas passando o parâmetro pagina=1 (que devolverá os contatos de 1 a 10000) e em seguida pagina=2 (que devolverá os contatos de 10001 a 15000)

Exemplo:

chamada:
GET http://teste.locaweb.com.br/admin/api/loginx/contatos/validos/?chave=42342324&pagina=1

resposta:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[{"nome":"mario","email":"mario@dominio.com"},
{"nome":"maria","email":"maria@dominio.com"}]

Importação

POST http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/contatos/importacao/?listas=[ID_LISTAS]&chave=[CHAVE]

[ID_LISTAS] = id das Listas separados por ";"(ponto e vírgula) para onde os contatos serão importados (pode ser obtido na página de Listas do Email Marketing)

obs: Atualmente o limite de contatos por importação é de 10mil contatos por requisição e o limite do content-legth é de 10MB.

Exemplo:

chamada:
POST http://teste.locaweb.com.br/admin/api/loginx/contatos/importacao/?listas=1;2&chave=42342324

[{"nome":"mario","email":"mario@dominio.com"},
{"nome":"maria","email":"maria@dominio.com"}]

resposta:
HTTP/1.1 200 OK

Desativação

PUT http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/contatos/desativacao/?listas=[ID_LISTAS]&chave=[CHAVE]

[ID_LISTAS] = id das Listas separados por ";"(ponto e vírgula) de onde os contatos serão removidos. Caso esse parâmetro não seja informado, o contato é desativado e não receberá mensagens de nenhuma lista

obs: Atualmente o limite de contatos por desativação é de 10mil contatos por requisição.

Exemplo:

chamada:
PUT http://teste.locaweb.com.br/admin/api/loginx/contatos/desativacao/?listas=1;2&chave=42342324

[{"email":"mario@dominio.com"},
{"email":"maria@dominio.com"}]

resposta:
HTTP/1.1 200 OK



Mensagens



Criação

POST http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/mensagem/?chave=[CHAVE]


Atributos requiridos (o corpo da mensagem deve conter todos os atributos abaixo, mesmo que seus valores estejam em branco):

Atributo Descrição Exemplo
identificador Um nome que identifique a mensagem (não é enviado para os destinatários) Mensagem 001
assunto Título da mensagem Promoção queima de estoque
nome_remetente O nome do remetente da mensagem Loja Certa
email_remetente Email do remetente (já deve estar cadastrado no Email Marketing
Mais detalhes [aqui])
eu.sobrenome@meuprovedor.com.br
dominio_dos_links Domínio dos links
Mais detalhes [aqui]
abcd.mkt9.com
id_campanha Numero de identificação da campanha
Pode ser obtido na página de Campanhas no Email Marketing
326545
formato A mensagem pode ser enviada no formato 'texto' ou 'html' ou em ambos os formato 'texto_e_html' texto_e_html
url_mensagem_html O link do Html a ser enviado
O Email Marketing fará o download do código fonte desta página
http//newsletter.meu.dominio.com.br/news01.html
mensagem_texto Corpo da mensagem texto
Caso deseje inserir quebras de linha, utilizar \n
Minha mensagem de texto 123
incluir_link_visualizacao Opção de incluir o link de visualização, valores possíveis 'true' ou 'false' true
texto_link_visualizacao Texto para descadastramento de usuário é importante que o texto contenha alguma frase entre '['
Só é obrigatório caso o atributo incluir_link_visualizacao seja true
Caso não visualize esse email adequadamente [acesse este link]

Exemplo:


Chamada:
POST http://teste.locaweb.com.br/admin/api/loginx/mensagem/?chave=42342324

{
 "identificador":"teste",
 "assunto":"teste",
 "nome_remetente":"fabio",
 "email_remetente":"fabio@gmail.com",
 "dominio_dos_links":"teste.mkt9.com",
 "id_campanha":"777",
 "formato":"texto_e_html",
 "url_mensagem_html":"http://dominio.tempsite.ws/teste.html",
 "mensagem_texto":"Minhas ofertas são muito boas.",
 "incluir_link_visualizacao":"true",
 "texto_link_visualizacao":"Caso não visualize esse email adequadamente [acesse este link]"
}

resposta:
HTTP/1.1 200 OK

{"id_mensagem":32}

Agendamento

PUT http://[HOSTNAME].locaweb.com.br/admin/api/[LOGIN]/mensagem/[ID_MENSAGEM]?chave=[CHAVE]


Atributos requiridos:

Atributo Descrição Exemplo
data_agendamento Deve estar no formato AAAA-MM-DD hh:mm:ss 2009-07-16 13:30:00
listas Ids das listas separadas por ';' 1;2;3
todos_contatos Essa opção envia a mensagem para todos os seus contatos, o único valor permitido para esse atributo é o 'true' true

IMPORTANTE: Não é permitido o uso conjunto dos atributos listas e todos_contatos, a mensagem deve ser enviada para uma ou mais listas OU para todos os contatos. (isso pode gerar um erro 409 - conflito)

Exemplo:


Chamada:
PUT http://teste.locaweb.com.br/admin/api/loginx/mensagem/1?chave=42342324

{
 "data_agendamento":"2009-07-16 13:30:00",
 "listas":"1;2;3"
}

resposta:
HTTP/1.1 200 OK

Download da API

Disponibilizamos alguns exemplos de código para a utilização da API para facilitar a utilização desta.

PHP

http://github.com/locawebemailmarketing/Locaweb-EmailMarketing-API

Veja também

Links

Ferramentas pessoais
Espaços nominais

Variantes
Ações
Navegação
Ferramentas
Criar um livro