APIs do Email Marketing

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: 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: Fiddler (http://www.fiddler2.com) Poster (plugin para Firefox) 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 Exportando contatos do Email Marketing para um arquivo .CSV Criando mensagens no Email Marketing Controle de bounces Adicionando remetente próprio no Email Marketing Relatórios do E-mail Marketing Gerando código para formulário de inscrição Links HelpDesk Painel de Controle Central de atendimento