Com a Mail API envia mensagens por email: envia um email para o endereço fixo da sua configuração, a seven avalia-o com base nos seus padrões e envia o resultado como SMS, RCS, mensagem de WhatsApp ou mensagem de voz. Onde se encontram o destinatário, o texto e o remetente no email, é algo que define uma única vez na configuração. Assim, a Mail API adapta-se à sua aplicação, por exemplo a uma ferramenta de monitorização, a uma loja online ou ao seu programa de email.
Como enviar mensagens depois disso, é explicado nos artigos Enviar SMS por email e Enviar RCS por email.
Criar uma configuração Mail API
Abra Programador -> Acessos à API. A lista mostra todas as chaves REST API, configurações Mail API e ligações SMPP. Clique em Criar nova no canto superior direito e escolha Mail API.
A caixa de diálogo Criar endereço Mail API guia-o pela configuração em cinco passos. Pode criar tantas configurações quantas quiser, cada uma com os seus próprios remetentes, endereço fixo e padrões.
Passo 1: Acesso
Em Remetentes permitidos, introduza os endereços de email a partir dos quais envia: um endereço por linha, até dez por configuração. O gateway não aceita emails de outros endereços. Com *@o-seu-dominio.pt autoriza todos os endereços de um domínio.
Não são permitidos:
- Endereços em domínios da própria seven (
seven.io,sms77.io,sms77.dee respetivos subdomínios) - Autorizações de domínio (
*@dominio) para fornecedores de email gratuito como Gmail ou GMX - Endereços que já estejam comprovados noutra conta seven
Estas verificações são feitas logo ao clicar em Seguinte, para que veja os erros diretamente no campo de introdução.
Passo 2: Padrões
Aqui descreve o aspeto dos seus emails. O texto literal do padrão tem de aparecer exatamente assim no email e serve de âncora; as variáveis entre chavetas duplas capturam o texto intermédio.
- Padrão do prefixo de endereço (predefinição: vazio): aplica-se à parte do endereço antes do token. Com
{{to}}, um email para4917612345678.TOKEN@gateway.seven.iovai exatamente para este número de telefone. Se o campo ficar vazio, envia os seus emails para o endereço sem prefixo e o destinatário vem das definições (passo 3). - Padrão do assunto (predefinição: vazio): vazio significa que o assunto é ignorado.
- Padrão do corpo (predefinição:
{{text}}): com a predefinição, todo o texto do email passa a ser o texto da mensagem.
As variáveis mais importantes são {{to}} (destinatário: número de telefone, contacto ou grupo), {{text}} (texto da mensagem) e {{from}} (ID de remetente). Em Avançado e WhatsApp encontra outras variáveis, por exemplo {{delay}} para o envio agendado ou {{label}}. A lista completa está na documentação da Mail API.
Exemplo: o padrão do corpo (({{text}})) delay={{delay}} corresponde ao email ((A sua encomenda está a caminho.)) delay=2027-01-15 08:00:00 e agenda a mensagem para 15/01/2027 às 8h00.
Passo 3: Definições
Em Predefinições define o que se aplica quando os padrões não fornecem nada:
- Destinatário fixo: aplica-se quando nenhum padrão captura
{{to}}e, nesse caso, é obrigatório. - Remetente da mensagem: aplica-se quando nenhum padrão captura
{{from}}. Vazio significa o remetente predefinido da sua conta. - Tipo: SMS, RCS, WhatsApp ou Voice.
Em Opções introduz opcionalmente um E-mail de erro para o qual devem ser enviadas as mensagens de erro.
Passo 4: Pré-visualização
Antes de poder guardar, verifica os seus padrões com um email real. Para isso, cada configuração tem um Endereço de teste com o sufixo -test, ou seja TOKEN-test@gateway.seven.io (com prefixo, por exemplo 4917612345678.TOKEN-test@gateway.seven.io). Com Abrir e-mail de exemplo, o seu programa de email prepara um email adequado.
Envie o email de teste a partir de um dos remetentes permitidos. Assim que chegar, vê as variáveis capturadas e a mensagem que daí resultaria. Os emails para o endereço de teste não desencadeiam qualquer envio.
Importante:
- Sem email de teste não é possível guardar a configuração, nem mesmo ao editá-la mais tarde.
- Um email de teste de um endereço que não esteja na lista de remetentes permitidos é mostrado, mas não conta. Nesse caso, envie a partir da conta correta.
- Se chegarem vários emails de teste, o mais recente que corresponda é a pré-visualização. Os anteriores podem ser expandidos.
- Se a sua rede bloquear a ligação em direto do dashboard, a caixa de diálogo obtém automaticamente os emails de teste recebidos a cada poucos segundos. Com Obter e-mail de teste agora desencadeia isso de imediato.
Passo 5: Segurança
No último passo vê o Endereço fixo da configuração (TOKEN@gateway.seven.io), a Comprovação do remetente para cada remetente permitido e o estado da Verificação DMARC. Com Guardar conclui a configuração, que fica imediatamente utilizável.
Comprovar remetentes e verificação DMARC
Por princípio, o gateway só aceita emails dos remetentes permitidos. Além disso, pode comprovar que os remetentes lhe pertencem de facto. Assim que todos os remetentes de uma configuração estiverem comprovados, a Verificação DMARC ativa-se automaticamente. Não existe um interruptor para isso.
Como comprovar remetentes:
- Endereço individual: envie a partir desse endereço um email de teste para o endereço de teste que passe na verificação DMARC. O email de teste do passo 4 já conta como comprovação se passar no DMARC.
- Autorização de domínio (
*@dominio): crie no domínio um registo TXTseven-mail-api-verify=TOKENe clique em Verificar DNS. Adicionalmente, o domínio (ou um domínio de nível superior) precisa de um registo DMARC. A seven verifica ambos diariamente e retira a comprovação se o registo TXT faltar durante alguns dias.
Com a verificação DMARC ativa, o gateway só aceita emails cujo domínio do remetente passe na verificação DMARC. O requisito é um registo DMARC do seu domínio em conjunto com SPF ou DKIM. Os reencaminhamentos não são problemáticos, desde que a assinatura DKIM se mantenha. Os emails rejeitados aparecem com o código 904 no Debugger. A mensagem de erro é então enviada exclusivamente para o endereço de E-mail de erro, nunca para o remetente, pois este pode ter sido falsificado.
Se um email de teste não passar na verificação, a caixa de diálogo indica o motivo, por exemplo que o domínio do remetente não tem registo DMARC, que nem SPF nem DKIM correspondem ao domínio do remetente ou que o resultado se refere a um domínio diferente do endereço From.
Bom saber: a uma configuração com verificação DMARC ativa já não pode adicionar remetentes não comprovados. Para remetentes sem DMARC, crie uma segunda configuração.
Endereço sem token
Com a verificação DMARC ativa, pode ativar adicionalmente no passo Segurança a opção Permitir adicionalmente o endereço sem token. Nesse caso, o prefixo basta como endereço completo, por exemplo 4917612345678@gateway.seven.io. A seven atribui o email apenas através do remetente comprovado da sua configuração. O endereço com token continua a funcionar. Se quiser combinar token e verificação DMARC, deixe a opção desativada.
Se o mesmo remetente comprovado utilizar várias configurações com esta opção, o email não é atribuído e não é enviado.
Definições adicionais da Mail API
Abra Programador -> Definições e expanda a secção Mail API. Estas definições aplicam-se a todas as configurações Mail API.
- Número máximo de caracteres: limita o comprimento da mensagem, para que assinaturas ou rodapés enviados por engano não façam disparar os custos.
0desativa o limite. - Remover assinatura: filtra o texto citado (
> como estas linhas) antes do envio. - Notificação em caso de erro / Envio HTTP em caso de erro: é informado por email ou por push HTTP quando um email não pode ser processado, por exemplo porque um padrão não corresponde ou falta o destinatário.
- Inserir remetente no SMS: antepõe à mensagem o endereço do remetente do email, à escolha como Endereço completo (
utilizador@dominio.pt), como Parte local (antes do @) (utilizador) ou não inserir de todo (Não anexar).
Configurações existentes (Legacy)
As configurações criadas antes da introdução do endereço fixo estão assinaladas na lista com Legacy. Continuam a funcionar no formato clássico: o número de telefone fica antes de @gateway.seven.io e os parâmetros de controlo como key=, from= ou type= ficam no assunto. As configurações Legacy funcionam sem alterações e por tempo ilimitado, mas só permitem um remetente e nenhuma verificação DMARC. Para novas aplicações, recomendamos uma configuração com endereço fixo e padrões.
Documentação
A referência completa com todas as variáveis, exemplos e o formato clássico encontra-se na documentação da Mail API.