README.rdoc

Mailee - Email marketing para quem entende de tecnologia.¶ ↑

¶ ↑

O problema¶ ↑

Você está desenvolvendo um sistema (e-commerce, cms, erp...) e o seu cliente solicita a possibilidade de enviar e-mails promocionais, ou notícias, para diversos contatos. Por experiência própria, você sabe que enviar e-mails não é coisa para _scriptkiddies_, e que, de fato, não vale a pena o esforço de desenvolver todo um sistema que faça o envio, garanta a entrega, analise os retornos e também apresente resultados de tudo isso. O problema é que os sistemas que você conhece não permitem uma integração fácil e rápida com seus sistemas em Rails...

A solução¶ ↑

Este plugin tem como objetivo manter os contatos da sua aplicação sincronizados com os contatos do Mailee (www.mailee.me) sem muito esforço. De fato, basta executar o método "sync_with_mailee" no seu modelo (clientes, contatos, pessoas...) que este irá automaticamente realizar as tarefas de inserir, atualizar, excluir e descadastrar via REST. No Mailee, seu cliente poderá então montar as mensagens e enviar para os contatos.

Instalação¶ ↑

* Execute o seguinte comando em sua aplicação Rails:
> script/plugin install git@github.com:softa/mailee-api.git
* Adicione a seguinte linha de configuração em sua aplicação:
Mailee::Config.site = 'http://api.chave.subdominio.wizee.net'
O site você descobre entrando no Mailee e indo em Configurações > Integração > REST

Pronto!

Uso¶ ↑

* Na mão (console)
Você pode usar a api do maile "na mão". Basta abrir o console e usar:
> ruby script/console
>> Contact.find(:all)
>> Contact.find(:first)
>> Contact.create(:name => 'Bertrand Russell', :email => 'russell@cambridge.edu.uk')
Mais exemplos você encontra(rá) na (futura) documentação da API.
* Com modelos (ActiveRecord)
Este plugin é feito para manter um modelo AciveRecord sincronizado com os contatos do Mailee. Para fazer isto, basta colocar o método "sync_with_mailee" em seu modelo. Se o seu modelo se chama "Contact", por exemplo, o código seria este:
=code
  class Contact < ActiveRecord::Base
    sync_with_mailee
  end
A priori, o plugin espera que você tenha pelo menos um campo de email e pressupõe que o nome deste campo é "email". Se o campo da sua tabela não tem este nome, você pode fazer o seguinte:
=code
  class Contact < ActiveRecord::Base
    sync_with_mailee :email => :my_email_column
  end
Onde "my_email_column" é a coluna que guarda o e-mail na sua tabela.
O plugin também pode manter o nome do seu contato sincronizado, bastando para isto ter um campo "name" que será mapeado por padrão, mas que também pode ser sobrescrito:
=code
  class Contact < ActiveRecord::Base
    sync_with_mailee :email => :my_email_column, :name => :my_name_column
  end  
Por fim, o plugin permite que o cadastro no Mailee seja condicionado a um campo booleano (o padrão é "news"), que corresponde ao "opt-in" (a escolha de receber ou não mensagens) do seu contato. Ou seja, se o valor do campo for false, o plugin não cadastrará o contato no Mailee, e se o contato já estiver cadastrado e o valor deste campo mudar para falso, o contato será descadastrado e _não_ poderá ser mais cadastrado no Mailee (normas de privacidade). Para mudar o campo, basta:
=code
  class Contact < ActiveRecord::Base
    sync_with_mailee :email => :my_email_column, :name => :my_name_column, :news => :do_you_really_accept_to_receive_our_newsletter
  end  
* Tarefas (rake)
Caso você já tenha itens cadastrados, é necessário adicionar estes contatos ao Mailee antes de mais nada. Para isso execute a tarefa rake:
> rake mailee:send CLASS=Contact
Onde "Contact" é o nome do seu modelo. Se você quer apenas enviar os contatos a partir de uma determinada data, você pode fazê-lo desta forma:
> rake mailee:send CLASS=Contact AFTER=5.days.ago
Neste caso, ele vai apenas sincronizar os contatos que foram atualizados (baseado no campo "updated_at") nos últimos 5 dias.  
* Mas... como isso funciona, caso eu precise saber?
O plugin utiliza a API REST do Mailee para enviar dados, por isto cuide bem da sua URL - se alguém descobrir isso pode ser ruim. Para saber qual o contato na sua aplicação o plugin utiliza um campo disponível no Mailee chamado "internal_id" o qual recebe o "id" da sua tabela na criação. Este id é usado nas atualizações, descadastros e exclusões, então tome (ou avise seu cliente para tomar!) cuidado ao editar este campo na interface do Mailee.

Dúvidas?¶ ↑

Qualquer dúvida, não hesite em falar conosco pelo e-mail suporte@mailee.me.