Mail API

A Mail API transforma os seus e-mails em mensagens: você envia um e-mail para o endereço da sua configuração, nós o avaliamos com base nos seus padrões e enviamos o resultado como SMS, RCS, WhatsApp ou mensagem de voz. Onde estão no e-mail o destinatário, o texto e o remetente, você descreve uma única vez na configuração. Os destinatários podem ser números, contatos ou grupos do seu catálogo de endereços.

Endereço fixo com padrões de e-mail

Cada configuração da Mail API possui um endereço fixo gerado pelo sistema e três padrões. Os padrões descrevem como são os seus e-mails: onde está o destinatário, onde está o texto da mensagem e o que mais o e-mail contém. Assim a Mail API se adapta à sua aplicação. A configuração em si é criada conforme descrito na seção Configuração.

Estrutura do endereço

O endereço é composto por um token fixo e um prefixo opcional à frente:

TOKEN@gateway.seven.io
PREFIX.TOKEN@gateway.seven.io

O TOKEN é gerado por nós, é fixo e é exibido no seu login em Desenvolvedor > Mail API. O PREFIX é você quem escolhe a cada e-mail: tudo o que estiver antes do último ponto da parte local é o prefixo e é avaliado pelo padrão do prefixo de endereço.

Assim, no endereço 01761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io, a1b2c3d4e5f6g7h8 é o token e 01761234567890 é o prefixo.

Endereço curto sem token

Com Verificar remetente via DMARC ativado na configuração, o token pode ser omitido: um e-mail para 01761234567890@gateway.seven.io é então atribuído à configuração apenas pelo seu endereço de remetente, e toda a parte local do endereço é o prefixo. Aqui contam apenas remetentes comprovados (veja Segurança). Se mais de uma configuração contiver o mesmo remetente comprovado, nenhuma delas é usada; um endereço comprovado tem prioridade sobre uma entrada de domínio comprovada. O endereço com token continua funcionando em qualquer caso.

Configuração em quatro passos

O diálogo em Desenvolvedor > Mail API conduz você pelos quatro passos de uma configuração.

Variáveis

Nos padrões você dispõe das seguintes variáveis. A lista é definitiva, não existem outras variáveis.

Básicas

Ampliadas: {{delay}}, {{type}}, {{label}}, {{foreign_id}}, {{unicode}}, {{flash}}, {{performance_tracking}}, {{get_replies}}

O significado e os valores permitidos destas variáveis estão descritos na seção Formato clássico, em Parâmetros, e valem aqui sem alterações. {{type}} substitui, para aquele e-mail, o tipo definido na configuração. {{get_replies}} aceita yes ou no: com yes enviamos a mensagem a partir de um número que pode receber respostas, para que o destinatário possa responder diretamente; um remetente definido é substituído por ele.

WhatsApp: {{template}}, {{template_lang}}, {{header}}, {{body}}, {{buttons}}, {{media_url}}, {{media_type}}, {{caption}}

Estas variáveis preenchem os campos de uma mensagem WhatsApp; o seu significado está descrito na seção WhatsApp (WA).

A autenticação é feita pelo seu endereço de remetente e pelo token do endereço; não existe chave.

Cada variável pode aparecer no máximo uma vez no conjunto dos três padrões. {{text}} precisa ser capturado por um dos padrões e {{to}} precisa ser capturado ou definido em Destinatário fixo.

Como avaliamos o e-mail

• O padrão do prefixo de endereço precisa cobrir todo o prefixo.
• No assunto e no corpo procuramos o padrão: o texto literal precisa aparecer e as variáveis capturam o texto intermediário.
• Um padrão vazio significa que essa parte do e-mail é ignorada.
• Um remetente capturado tem prioridade sobre Remetente da mensagem, e um destinatário capturado sobre Destinatário fixo.
• Se um padrão não corresponder à respectiva parte do e-mail, a mensagem não é enviada.

Segurança

A verificação do remetente permanece inalterada: aceitamos apenas e-mails de um dos endereços de remetente que você registrou na respectiva configuração ou de um endereço de um domínio ali registrado (*@dominio).

Verificar remetente via DMARC

Para maior segurança, a opção Verificar remetente via DMARC pode ser ativada por configuração. Nesse caso, só aceitamos um e-mail se o domínio do remetente (o domínio do endereço From) passar na verificação DMARC no nosso gateway. Isso exige um registro DMARC do seu domínio junto com SPF ou DKIM; um domínio sem registro DMARC nunca passa na verificação. Encaminhamentos não são um problema desde que a assinatura DKIM permaneça intacta.

A opção só pode ser ativada quando todos os remetentes da configuração estiverem comprovados. Um endereço de remetente é comprovado enviando a partir dele, para o endereço de teste da configuração, um e-mail de teste que passe na verificação DMARC. Uma entrada de domínio (*@dominio) é comprovada por um registro TXT seven-mail-api-verify=TOKEN no domínio; verificamos o registro diariamente e retiramos a comprovação se ele faltar por alguns dias. Entradas de domínio não são possíveis para domínios de e-mail gratuito, e um endereço de remetente comprovado numa conta não pode mais ser registrado em nenhuma outra conta.

Um e-mail rejeitado aparece com o código 904 no seu Depurador. Nesse caso, o e-mail de erro é enviado exclusivamente para o endereço de erro registrado e nunca para o remetente do e-mail, pois ele pode ter sido falsificado.

Exemplos

Configuração padrão

Sem ajustar os padrões, todo o corpo passa a ser o texto da mensagem. O destinatário está definido na configuração e o e-mail vai para o endereço sem prefixo.

Resultado: um SMS para 01761234567890 com o texto "Sua encomenda está a caminho." O assunto é ignorado.

Destinatário no endereço

Se cada e-mail deve ir para um número diferente, capture o destinatário com {{to}} no prefixo do endereço. Um destinatário fixo não é necessário nesse caso.

Resultado: um SMS para 01761234567890 com o texto "Sua encomenda está a caminho."

Alerta no assunto, destinatário fixo

Uma ferramenta de monitoramento envia o seu alerta no assunto para um endereço fixo. O destinatário está definido na configuração.

Resultado: um SMS para 01761234567890 com o texto "Carga de CPU crítica em srv-07".

Padrão com âncoras

Se o e-mail contiver mais do que apenas o texto da mensagem, delimite-o com texto literal. Aqui dois pares de parênteses envolvem o texto, seguidos do momento do envio.

Resultado: um SMS para 01761234567890 com o texto "Seu pedido está a caminho.", agendado para 15 de janeiro de 2027 às 08:00. A data do exemplo representa qualquer momento futuro que a sua aplicação defina.

Tratamento de erros

Se um padrão não corresponder à respectiva parte do e-mail ou se o destinatário ficar vazio, a mensagem não é enviada. Você receberá um e-mail de erro indicando o motivo, desde que tenha ativado a opção "Notificar em caso de erros". Com Verificar remetente via DMARC ativado, o mesmo vale para e-mails cujo domínio do remetente não passe na verificação DMARC; esse e-mail de erro é enviado apenas para o endereço de erro.

Configuração

No seu login na área de Desenvolvedor em Mail API, você gerencia as suas configurações. O ícone verde + no canto inferior direito cria uma nova; o diálogo conduz você pelos quatro passos descritos acima. Você pode criar quantas configurações desejar, cada uma com os seus próprios remetentes permitidos, o seu próprio endereço fixo e os seus próprios padrões. Configurações recém-criadas podem ser usadas imediatamente após o salvamento.

Clicando nas engrenagens azuis, você acessa as opções de configuração para a Mail API.

Configurações Mail API

• Comprimento máximo: Defina um número máximo de caracteres para evitar mensagens muito longas devido ao envio de assinaturas. Insira 0 para desativar esta função.
• Remover citações: Se ativado, a API tentará remover automaticamente o texto citado no e-mail.
• Notificar em caso de erro: Esta opção determina se você deseja receber uma notificação por e-mail em caso de erros. Se, por exemplo, o envio da mensagem falhar, um padrão não corresponder ao seu e-mail ou faltarem dados como o destinatário, enviaremos diretamente um e-mail com informações sobre o erro. Ao criar uma configuração, você pode opcionalmente especificar um endereço de e-mail alternativo para receber as mensagens de erro.
• Incluir remetente do e-mail no texto: Aqui você pode definir se deseja enviar uma parte do endereço de e-mail no início da sua mensagem. Você pode escolher entre três opções:

Formato clássico

As configurações criadas antes da introdução do endereço fixo funcionam no formato clássico: o destinatário está na parte local do endereço e os parâmetros estão no assunto. No dashboard elas aparecem marcadas como Legacy e continuam funcionando sem alterações e por tempo indeterminado. As novas configurações utilizam padrões de e-mail.

Estrutura do e-mail

Os e-mails dirigidos a uma configuração Legacy têm a estrutura descrita abaixo. As novas configurações utilizam o endereço fixo com padrões de e-mail.

Destinatário

Para enviar uma mensagem através da API de e-mail, envie um e-mail para destinatario@gateway.seven.io substituindo destinatario pelo número do destinatário ou pelo nome do contato do seu catálogo de endereços.

Por exemplo, se você deseja enviar uma mensagem para o número 01761234567890, o destinatário deve ser 01761234567890@gateway.seven.io.

Assunto

No assunto, insira os parâmetros necessários para controlar o envio da mensagem. Estes devem ser separados por um espaço. Para definir um parâmetro, escreva o nome do parâmetro seguido de um sinal de igual e o valor do parâmetro.

Por exemplo, com umParametro=umValor, o parâmetro umParametro é definido como umValor. Se o parâmetro contiver espaços, você deve colocá-lo entre aspas duplas – por exemplo, umParametro="Um valor com espaços".

Conteúdo

O texto da mensagem deve ser enviado no corpo do e-mail. O gateway utiliza primeiro a parte text/plain do e-mail. Se o e-mail contiver apenas uma parte text/html sem alternativa de texto, tentará analisar e extrair o texto do conteúdo HTML. Naturalmente, este método nem sempre funciona como desejado.

Você pode opcionalmente envolver o texto da mensagem com ## para evitar que linhas vazias ou a assinatura do e-mail sejam incluídas na mensagem. O texto ficaria assim: ##Este é o texto## - apenas a parte entre ##...## será enviada na mensagem.

Parâmetros

Todos os parâmetros são especificados no assunto do e-mail, conforme mencionado acima. Se não for possível alterar o assunto do e-mail, você pode especificar os parâmetros no endereço do destinatário da seguinte forma:

• 01761234567890.from=ZahnPraxis@gateway.seven.io
• 01761234567890.from=ZahnPraxis.type=rcs@gateway.seven.io
• key=MAIL_API_KEY.from=ZahnPraxis.to=01761234567890@gateway.seven.io

Aqui está uma visão geral dos possíveis parâmetros:

WhatsApp (WA)

A Mail API também envia mensagens WhatsApp. Numa configuração com padrões de e-mail, defina o tipo como WhatsApp e informe o seu ID do serviço WhatsApp Frontend (Formato: WA-XXXXXXXX) como remetente da mensagem; numa configuração Legacy, defina type=WA e o parâmetro from. O ID está no seu painel seven.io em WABA → Services. Os campos a seguir estão disponíveis nos dois casos: como variáveis nos padrões ou como parâmetros no assunto.

Tipos de mensagens WhatsApp

O WhatsApp suporta três tipos de mensagens, que são determinados automaticamente com base nos parâmetros:

se template != null:
    → Mensagem template
senão se media_url != null:
    → Mensagem de mídia
senão:
    → Mensagem de texto (corpo do e-mail)

Mensagens template

Mensagens template são necessárias para mensagens fora da janela de 24h e devem ser pré-aprovadas pelo WhatsApp.

Mensagens de mídia

Mensagens de mídia só podem ser enviadas dentro da janela de conversa de 24h.

Mensagens de texto

Para mensagens de texto simples dentro da janela de 24h, o corpo do e-mail é usado como mensagem.

Exemplos WhatsApp (formato clássico)

1. Mensagem template (fora da janela de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=order_confirmation.template_lang=pt_BR.body=Joao,12345@gateway.seven.io

2. Template com imagem de cabeçalho

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=promo_image.header=https://example.com/promo.jpg.body=20%25-desconto@gateway.seven.io

3. Mensagem de texto (dentro da janela de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C@gateway.seven.io

4. Enviar imagem (dentro da janela de 24h)

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=image.media_url=https://example.com/produto.jpg.caption=Seu-produto@gateway.seven.io

5. Enviar documento

Para: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=document.media_url=https://example.com/fatura.pdf.caption=Sua-fatura@gateway.seven.io

Segurança

O caminho de transporte entre os servidores SMTP individuais ou o cliente SMTP geralmente é criptografado por TLS. No entanto, por vários motivos, é sensato criptografar o e-mail, razão pela qual a API de e-mail suporta criptografia por PGP e S/MIME:

1. Confidencialidade: PGP e S/MIME criptografam o conteúdo dos e-mails, de modo que apenas o destinatário pretendido pode descriptografá-los e lê-los. Isso garante a confidencialidade da comunicação.

2. Autenticação: Ambos os padrões permitem verificar a identidade do remetente. Assinaturas digitais, criadas com a chave privada do remetente, permitem que o destinatário assegure-se de que o e-mail realmente veio da fonte indicada e não foi manipulado.

3. Integridade: PGP e S/MIME oferecem mecanismos para verificar a integridade dos e-mails. Através de assinaturas digitais, o destinatário pode garantir que o conteúdo do e-mail não foi alterado desde o envio.

4. Defesa contra ataques Man-in-the-Middle: Através da criptografia e autenticação, PGP e S/MIME ajudam a prevenir ataques Man-in-the-Middle, onde um invasor intercepta, manipula e depois retransmite o tráfego de dados sem que as partes envolvidas percebam.

No geral, PGP e S/MIME são, portanto, úteis para garantir a segurança, confidencialidade e integridade da comunicação por e-mail, especialmente em ambientes onde informações sensíveis ou confidenciais são trocadas.

Para um envio criptografado dos e-mails, por favor, baixe o respectivo certificado e instale-o em seu sistema. Como os certificados PGP e S/MIME só podem ser vinculados a um único endereço de e-mail, envie seus e-mails para o endereço de e-mail indicado abaixo para o certificado.

O destinatário e os demais dados são informados, como no formato clássico, através dos respectivos parâmetros no assunto, por exemplo to=017612345678.

Aqui você pode baixar o respectivo certificado:

DMARC, DKIM, SPF

DKIM, SPF e DMARC são mecanismos para melhorar a segurança de e-mails. Eles ajudam a verificar a autenticidade dos e-mails, combater spam e phishing, além de melhorar a entregabilidade dos e-mails.

Nosso gateway verifica cada e-mail recebido em relação a SPF, DKIM e DMARC. Por padrão, o resultado é apenas informativo: o que decide a aceitação continua sendo a comparação com os endereços de remetente registrados. Somente com a opção Verificar remetente via DMARC na sua configuração da Mail API os e-mails cujo domínio do remetente não passa na verificação DMARC são rejeitados (código 904, veja Segurança acima). Você pode visualizar e-mails rejeitados no seu Depurador.

Exemplos do formato clássico

Primeiro exemplo

No primeiro exemplo, uma SMS é enviada para o número 0163123456789 do remetente ZahnPraxis. A chave neste caso é email2sms_key.

O texto que deve ser transmitido na SMS é:

Olá Sr. Schubert, gostaríamos de lembrá-lo sobre sua consulta em 20 de janeiro em nosso consultório. Estamos ansiosos para vê-lo! Até lá, seu consultório odontológico

Segundo Exemplo

Neste segundo exemplo, uma SMS é enviada para o contato Bartscher do remetente Optiker. O número padrão 0163123456789, que está no destinatário do e-mail, é sobrescrito pelo parâmetro to. A chave aqui é 123456789.

O texto que deve ser transmitido na SMS é:

Olá Sra. Bartscher, seus óculos estão prontos! Por favor, venha buscá-los em breve. Estamos ansiosos para vê-la! Até lá, seu Optiker – a assinatura do e-mail abaixo não será enviada na SMS, pois o texto está delimitado por ##.

Terceiro Exemplo

Neste exemplo, uma SMS é enviada para o número 0163123456789. As configurações para o remetente são usadas a partir das configurações padrão da sua conta em Configurações > SMS. A chave está diretamente integrada no destinatário do e-mail e definida como abcd123456.

O texto que deve ser transmitido na SMS é:

Olá Sra. Bartscher, seus óculos estão prontos! Por favor, venha buscá-los em breve. Estamos ansiosos para vê-la! Até lá, seu Optiker

A assinatura do e-mail abaixo não será enviada na SMS, pois o texto está delimitado por ##.

Legado

Por razões de compatibilidade retroativa, a API de e-mail permanece disponível no antigo endereço de destinatário email2sms@sms77.de para e-mails no formato da época. Os e-mails continuarão a ser processados como de costume. No entanto, recomendamos a mudança para uma configuração com endereço fixo e padrões de e-mail para aproveitar todas as funcionalidades.