Começar agora

Documentação

Tudo o que você precisa para integrar a EmailCompany e começar a entregar emails transacionais na caixa de entrada

Comece por aqui
1
Como enviar um email
2
Template
3
Requisição RESTful
4
Resultado
5
Bibliotecas de API
Documentação

Como enviar um email usando um servidor e um template associado

Para o envio de um ou mais emails, deverá ser feita uma requisição ao endpoint usando POST com um JSON válido. O único atributo necessário é o to, que é uma lista compreendendo um ou vários containers. Cada item da lista é um dicionário contendo os seguintes campos:

  • to - Destinatário(s) da mensagem*
  • name - Nome do destinatário
  • email - Endereço de e-mail do contato*
  • merge_vards - Variáveis de personalização
  • attachment - Anexo da mensagem
  • from - Remetente do e-mail
  • subject - Linha de assunto da mensagem
  • text - Conteúdo da mensagem em versão text/plain
  • html - Conteúdo da mensagem em versão text/HTML
  • template - Nome do template criado no sistema (carrega from, subject, text e html)
  • tracking_domain - Domínio utilizado para rastreamento (deve estar cadastrado e validado na EmailCompany)
  • return_path_domain - Domínio de Return-path (deve estar cadastrado e validado na EmailCompany)
  • html_click_tracking (boolean) - Habilita/desabilita o rastreamento de links na versão HTML
  • text_click_tracking (boolean) - Habilita/desabilita o rastreamento de links na versão text
  • open_tracking - (boolean) - Habilita/desabilita o registro de aberturas na versão HTML
  • unsubscribe_tracking (boolean) - Habilita/desabilita inserção do link de descadastro (Unsubscribe)
  • enable_list_unsubscribe (boolean) - Habilita/desabilita descadastro por lista (caso habilitada a lista padrão no Servidor)
  • show_unsubscribe_lists (boolean) - Exibe listas onde o contato está inserido na tela de descadastro, para seleção do mesmo
  • bcc_to - Adiciona destinatário(s) oculto(s)
  • auto_text (boolean) - Gera versão text do conteúdo a partir do HTML
  • auto_html (boolean) - Gera versão HTML do conteúdo a partir do text (em formato Markdown)
  • preserve_recipients (boolean) - Preserva os destinatários em todas as mensagens, exibindo os to para todos os destinatários
  • add_vcard (boolean) - Adiciona VCARD em anexo nos e-mails com os dados do remetente
  • add_custom_footer (boolean) - Habilita/desabilita rodapé personalizado (configurável no Servidor)
  • sandbox_to - Sobrescreve destinatário final para envio em modo Sandbox, para testes
  • enable_dkim (boolean) - Habilita/desabilita assinatura digital do e-mail (DKIM/DomainKeys)

*obrigatório

É obrigatório informar o remetente do email. Os outros campos são opcionais.

Os dados do remetente, Nome, Email e Assunto serão resgatados do template salvo e utilizados para formatar o email a ser enviado.

O campo merge_vars é um dicionário que será injetado no contexto do template para a personalização de campos. Neste dicionário, você pode inserir quantas variáveis de personalização desejar. Este contexto afeta inclusive o Assunto que pode ser personalizado também.

1

"merge_vars": {"birthdate":"02/08/1984", "gender":"male"}

A personalização de campos no Template é feita substituindo automaticamente as variáveis do template pelas variáveis injetadas pelo merge_vars. A sintaxe utilizada nos templates é a sintaxe do Jinja2 com todos os seus recursos.

Vamos ver um exemplo completo:

Template

1

<html>

2

<body>

3

Teste de personalização<br>

4

Name: \{\{contact.name\}\}<br>

5

Email: \{\{contact.email\}\}<br>

6

Cargo: \{\{cargo\}\}<br>

7

</body>

8

</html>

Note que os campos das variáveis são delimitados por \{\{ \}\}. Onde o conteúdo estiver delimitado por \{\{ \}\} o sistema tentará transformar em variáveis injetadas pelo merge_vars.

Isso vale inclusive para o Assunto do email como por exemplo: 

Subject: Welcome \{\{contact.name\}\}

Requisição RESTful

Faça uma requisição

Endpoint: http://api.emailcompany.io/v1/mail/
Method: POST
Authorization: Basic
Content-Type: application/json

1

{

2

                                  "template": "EmailCompany Template",

3

                                  "to": { 

4

                                          "name": "João Silva",

5

                                          "email": "joao.silva@empresabrasileira.com.br" 

6

                                           "merge_vars": {

7

                                                 "job_title": "CEO"

8

                                 }

9

                }

10

 }

Veja o mesmo exemplo enviado pelo Curl

1

"curl -­?v -­?-­?user 933ff2214029fffe19c:8107ff48ff6bc4fb19

2

    http://api.emailcompany.io/v1/mail/

3

    -­?H "Content-­?Type: application/json"

4

    -­?d {"to": [{

5

                                          "name":"João Silva",

6

                                           "email": "joao.silva@empresabrasileira.com.br",  "merge_vars": {

7

                                           "merge_vars": {"cargo": "CEO"}

8

                                 }]

9

                }

Para a autenticação, deve-se utilizar o Basic Authorization, passando a API KEY e a API SECRET como dados.

Resultado

O resultado da postagem, se o JSON estiver formatado corretamente e a autorização tiver sido dada, será um JSON contendo uma lista com cada um dos emails enviados e um identificador único de evento.

201 Created

...

Bibliotecas de API

Através das nossas bibliotecas você será capaz de fazer uma integração rápida entre a EmailCompany e seu projeto com uma variedade de linguagens e frameworks. Nós mantemos as seguintes bibliotecas oficiais para você enviar seus emails transacionais:

EmailCompany-nodejs - Biblioteca oficial NodeJS

EmailCompany-php - Biblioteca oficial PHP

EmailCompany-python - Biblioteca oficial Python

EmailCompany-ruby - Biblioteca oficial Ruby

Exemplos de código

Nodejs

1

".. code:: javascript

2