Roteamento de e-mail de entrada em PHP
O envio de e-mails é, sem dúvida, o recurso mais conhecido por quem usa o Mailgun, mas a plataforma pode fazer muito mais do que apenas enviar e-mails e rastrear análises. Quando as pessoas me perguntam do que mais gosto no Mailgun, quase sempre digo o quanto a API é intuitiva e bem documentada. Há um recurso específico, no entanto, sobre o qual gosto de falar: o sistema de roteamento e análise de e-mail de entrada, também conhecido como “Routes” no painel de controle.
O roteamento de e-mail de entrada significa que você pode configurar o Mailgun para receber e-mails em seu nome. Você pode configurá-lo com um domínio inteiro ou um subdomínio de sua escolha. Acredito que usar um subdomínio seja a melhor opção, pois só é possível configurar um serviço para receber seus e-mails de cada vez.
Isso significa que não é possível usar seu cliente de e-mail e o recurso de entrada do Mailgun no mesmo domínio. Por esse motivo, tenho uma configuração como a seguinte:
- orlando@domain.com: que uso com um cliente de e-mail normal
- robots@inbound.domain.com: que lida com outros fluxos de trabalho de e-mail por meio da API de entrada do Mailgun.
Assim que um e-mail é recebido, o Mailgun pode fazer algumas coisas com ele: enviá-lo para outro endpoint de sua escolha, redirecioná-lo para outro e-mail ou armazená-lo para que você possa processá-lo depois.
Legal! Para que eu o uso?
Processar todos os anexos!
E se você pudesse usar e-mails para criar um aplicativo que recebesse anexos e os enviasse automaticamente para sua conta de armazenamento online (como Dropbox, Google Drive ou semelhante)?
E se esse e-mail pudesse entender quem está enviando os anexos, o que eles contêm e classificá-los adequadamente?
Boas notícias: com o roteamento de e-mail do Mailgun, você pode!
Para fazer isso, basta especificar um filtro em um domínio ou subdomínio. Para começar, acesse as rotas no painel de controle e lembre-se de que será necessário alterar as configurações de DNS do seu domínio para que os registros MX apontem para o Mailgun.
Uma rota é composta por um filtro, uma ação, uma descrição para facilitar a compreensão humana do que ela faz e uma prioridade.
Um filtro pode ser de um dos seguintes tipos:
match_recipient(pattern): onde o padrão é uma expressão regular de um endereço de e-mailmatch_header(header, pattern): onde o cabeçalho é um (cabeçalho MIME) e o padrão é uma expressão regularcatch_all(): geralmente tem a prioridade mais baixa, pois encaminha qualquer e-mail de entrada
Você pode especificar o filtro acima para realizar ações de forma dinâmica; se o filtro corresponder a um endereço especificado, uma ação resultante ocorrerá. Há uma lista de ações abaixo. Lembre-se de que você pode ter mais de uma ação ao mesmo tempo:
Forward(): encaminha o e-mail para outro endereço de e-mail ou URLStore(): salva o e-mail correspondente no servidor do Mailgun por até três dias para uso posterior ou atrasado.Stop(): simplesmente interrompe a cadeia de ações. Isso é necessário para evitar que a mensagem continue sendo processada por outras ações. (falarei sobre isso com mais detalhes depois)
Priorize as rotas atribuindo-lhes prioridades conforme necessário.
- Número baixo = alta prioridade
- Número alto = baixa prioridade
Rotas com a mesma prioridade recebem preferência com base na data de criação.
Depois de configurar o DNS do seu domínio ou subdomínio para encaminhar e-mails para o Mailgun, conforme explicado na documentação, com as configurações indicadas na página do seu domínio, você pode começar a parte divertida!
Criação, edição e exclusão de rotas em PHP
Após instalar a biblioteca PHP, podemos criar um novo arquivo chamado createRoutes.php
post("routes", array(
'priority' => $CONST_PRIORITY,
'expression' => 'match_recipient("'. $CONST_RECIPIENTEXP.'")',
'action' => array('forward("'.$CONST_FORWARDTO.'")', 'stop()'),
'description' => $CONST_DESCRIPTION
));
?>
Que tal listar todas as rotas para verificar de forma programática quais você já criou e, eventualmente, editá-las?
get(
"routes", array('skip' => 0, 'limit' => 10)
);
#Let's print some output, ofcourse you can iterate the object $result to find more information regarding the routes!
print "<strong>The whole object:</strong>";
print "<br>";
print_r($result);
print "<br>";
print "<strong>The expression assigned to the first route:</strong>";
print "<br>";
print $result->http_response_body->items[0]->expression;
print "<br>";
?>
Neste momento, criamos uma rota com sucesso.
Toda vez que o Mailgun receber um e-mail de alguém em *@sampleprovider.com, ele pegará a mensagem e enviará um webhook com seu conteúdo para http://samplewebsite.com/webhook.
Agora, do meu lado (supondo que http://samplewebsite.com/webhook seja meu servidor), quero capturar o conteúdo do webhook que é enviado quando um filtro intercepta um e-mail de entrada.
O Mailgun envia diversos tipos de cabeçalhos; a maioria está listada abaixo:
Content-Type
Date
From
In-Reply-To
Message-Id
Mime-Version
Received
References
Subject
To
X-Envelope-From
X-Mailgun-Incoming
X-Received
body-html
body-plain
domain
from
message-headers
message-url
recipient
sender
signature
stripped-html
stripped-signature
stripped-text
subject
timestamp
token
Vamos supor que queremos gravar em um arquivo o corpo da mensagem sem qualquer HTML, quebras de linha e retornos.
O código a seguir será executado pelo PHP quando o webhook enviado pelo Mailgun for recebido e gravará o conteúdo do corpo da solicitação (neste caso, escolhi stripped-text, mas poderia ser qualquer um dos anteriores) em um arquivo chamado output.txt
Como você pode ver, as opções a partir daqui são infinitas!
Se você tiver interesse em saber mais sobre as funcionalidades de roteamento de e-mail de entrada, acesse a página de documentação ou fique à vontade para fazer perguntas ou comentar aqui ou no Twitter.
Bons envios!
