Introdução ao e-mail

A Messages API do Vonage oferece suporte ao e-mail como canal, permitindo que você envie e-mails transacionais usando o mesmo contrato de API que já utiliza para outros canais de mensagens.

Pré-requisitos

Antes de começar, certifique-se de ter:

• A Account da API da Vonage
• Sua chave de API e seu segredo de API do Painel de Controle da API da Vonage
• Um domínio de remetente que você pode gerenciar no DNS
• Acesso à versão beta do canal de e-mail

Integração por e-mail

Para começar a usar a API de e-mail:

1. Forneça as seguintes informações ao seu gerente de contas:
   • Sua chave de API da Vonage
   • O(s) domínio(s) personalizado(s) que você pretende usar para o envio (por exemplo, yourdomain.com)
   • Sua região preferida para verificação de domínio (US, EU, ou APAC)
2. Seu gerente de contas repassa essas informações à equipe interna para dar início ao processo de integração.
3. A Vonage fornece os registros DNS que você precisa adicionar ao seu domínio. Consulte Configuração da autenticação de domínio.
4. Após atualizar o DNS, confirme a conclusão com seu gerente de Accounts. A verificação do DNS pode levar até 72 horas.
5. Adicione os registros DNS o mais rápido possível. Se a propagação demorar mais do que o esperado, abra um ticket de suporte ou entre em contato com seu gerente de contas.
6. Assim que a verificação for concluída com sucesso, a Vonage notificará seu gerente de Account e você poderá começar a enviar e-mails usando a Messages API.

Configuração da autenticação de domínio

Antes de enviar e-mails, você precisa autenticar seu domínio de envio. A autenticação do domínio melhora a capacidade de entrega e permite que os provedores de e-mail verifiquem se a Vonage está autorizada a enviar mensagens em seu nome.

A autenticação é concluída com a adição de registros DNS ao seu domínio. Esses registros permitem:

• SPF (Sender Policy Framework) para autorizar a infraestrutura de envio da Vonage.
• DKIM (DomainKeys Identified Mail) para assinar criptograficamente o conteúdo dos e-mails enviados.
• DMARC (Autenticação, Relatórios e Conformidade de Mensagens com Base no Domínio) para definir políticas e relatórios relativos a falhas de autenticação.

Os principais provedores de e-mail, incluindo Google, Microsoft e Yahoo, se baseiam nessas normas ao decidir se devem entregar, rejeitar ou filtrar mensagens.

Para mais informações, consulte Fatores que afetam a capacidade de entrega dos seus e-mails.

Registros DNS a serem configurados

A Vonage fornece os valores exatos durante a integração. A tabela abaixo mostra a estrutura esperada dos registros:

Melhores práticas de autenticação

• Configure todos os registros DKIM fornecidos pela Vonage para cada domínio remetente.
• Comece com o DMARC p=none durante o monitoramento e, quando estiver tudo pronto, aplique políticas mais rigorosas.
• Adicione a Vonage ao seu registro SPF usando include:msg.vonage.com.
• Se você já tiver um registro SPF, acrescente o trecho da Vonage em vez de substituir as entradas existentes.

Exemplo:

• SPF existente: v=spf1 include:example.com ~all
• Fator de proteção solar (FPS) atualizado: v=spf1 include:example.com include:msg.vonage.com ~all

Opções avançadas de DNS

• Clique e abra o DNS de rastreamento: a Vonage pode fornecer registros CNAME adicionais para a configuração de rastreamento.
• Personalizado mail from / caminho de retorno: A Vonage oferece suporte à configuração personalizada do caminho de retorno e pode fornecer registros MX e TXT adicionais.

Pergunte ao seu gerente de contas se você precisa dessas opções avançadas durante o processo de integração.

Envie seu primeiro e-mail

Assim que seu domínio for verificado, você estará pronto para enviar mensagens de e-mail usando a Messages API.

Criar uma aplicação da Vonage (opcional)

Para usar a Messages API, é necessário ter um aplicativo da Vonage com o recurso de Mensagens ativado.

1. Acesse Criar um aplicativo no Painel da Vonage.
2. Digite o nome do aplicativo.
3. Clique Gerar chave pública e chave privada e armazene a chave privada com segurança.
4. Sob Recursos, ativar Mensagens.
5. Configure seus webhooks de URL de entrada e URL de status.
6. Clique Criar um novo pedido.

Para obter mais informações, consulte Criar uma aplicação da Vonage.

Defina seus valores substituíveis

Utilize as seguintes variáveis nos exemplos e substitua-as pelos seus próprios valores:

Gerar um JWT

A Messages API utiliza autenticação JWT. Gere um JWT usando seu ID de aplicativo e sua chave privada antes de chamar a API.

Enviar uma mensagem de texto por e-mail

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "text",
   "text": "Email body text",
   "email": {
      "subject": "Email subject"
   }
}

Se a operação for bem-sucedida, a resposta da API contém message_uuid:

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Enviar um e-mail em HTML

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "html",
   "html": {
      "body": "<p>Email body html</p>"
   },
   "email": {
      "subject": "Email subject"
   }
}

Limites de tamanho de e-mails

O corpo do e-mail suporta até 100 KB por solicitação de API. Se o corpo exceder esse limite, a solicitação retornará um erro.

A Messages API também impõe um limite de carga útil de 200 KB no nível da rede.

Verificar o status da entrega

Após o envio de um e-mail, a Vonage envia atualizações sobre o status da mensagem para a URL de status configurada por você.

Fatores que afetam a capacidade de entrega dos seus e-mails

A capacidade de entrega de e-mails é a capacidade de uma mensagem de e-mail chegar à caixa de entrada do destinatário.

Delivery e deliverability são diferentes:

• “Entrega” significa que o servidor de e-mail de destino aceitou a mensagem.
• A capacidade de entrega significa que a mensagem chega à caixa de entrada, em vez de ir para a pasta de spam ou ser rejeitada.

Modelo de Responsabilidade Compartilhada

A capacidade de entrega de e-mails é uma responsabilidade compartilhada entre a Vonage e o cliente.

1. Autenticação de domínio

A autenticação de domínio é um dos fatores mais importantes para a capacidade de entrega.

• O DKIM assina o conteúdo da mensagem.
• O DMARC define a política de tratamento para falhas de autenticação.
• O SPF autoriza remetentes aprovados.

Essas normas ajudam os provedores de e-mail a verificar a identidade do remetente e a integridade das mensagens.

2. Reputação do remetente

Os provedores de e-mail avaliam continuamente a reputação dos domínios e dos endereços IP.

Uma má reputação pode levar a:

• Envio para a pasta de spam
• Limitação temporária
• Rejeição de mensagem
• Menor visibilidade na caixa de entrada

A reputação é influenciada por reclamações de spam, taxas de rejeição, consistência no envio, engajamento dos usuários e qualidade das mensagens.

Melhores práticas:

• Envie apenas para destinatários que esperam receber suas mensagens.
• Evite picos repentinos no volume de envios.
• Remova regularmente os destinatários inativos.
• Acompanhe as taxas de rejeição e de reclamações.

3. Qualidade do conteúdo dos e-mails

Os provedores de e-mail também avaliam a qualidade do conteúdo das mensagens.

Links quebrados, anexos suspeitos, conteúdo excessivo composto apenas por imagens ou arquivos muito grandes podem afetar negativamente a capacidade de entrega.

Melhores práticas:

• Use domínios confiáveis nos links.
• Mantenha o conteúdo da mensagem claro, relevante e bem estruturado.
• Mantenha um equilíbrio saudável entre texto e imagens.
• Valide os anexos e mantenha o tamanho da carga útil dentro dos limites permitidos.

4. Engajamento dos destinatários

Os provedores de e-mail utilizam indicadores de engajamento dos destinatários para determinar a colocação das mensagens na caixa de entrada.

Os sinais positivos incluem aberturas, cliques, respostas e a transferência de mensagens da pasta de spam para a caixa de entrada. Os sinais negativos incluem reclamações, exclusão imediata e inatividade prolongada.

Um maior engajamento geralmente melhora a reputação do remetente.

5. Gerenciamento de rejeições

Os rejeições definitivas e temporárias afetam a reputação do remetente de maneiras diferentes.

• Rejeição definitiva: falha permanente (por exemplo, endereço inválido ou destinatário inexistente).
• Rejeição suave: falha temporária (por exemplo, caixa de correio cheia ou problema temporário no servidor).

A Vonage processa automaticamente os eventos de rejeição e gerencia o comportamento de supressão para reduzir as tentativas repetidas de entrega a destinatários que não podem receber mensagens de forma permanente.

6. Reclamações sobre spam

As reclamações sobre spam estão entre os sinais negativos de confiança mais fortes utilizados pelos provedores de e-mail.

Altas taxas de reclamações podem causar:

• Menor visibilidade na caixa de entrada
• Bloqueios temporários
• Dano permanente à reputação

Melhores práticas:

• Envie apenas para usuários que tenham dado consentimento.
• Identifique claramente sua organização.
• Torne o cancelamento da inscrição fácil e visível.
• Atenda prontamente aos pedidos de cancelamento de inscrição.

A Vonage processa eventos de spam e impede o reenvio para os destinatários afetados.

7. Qualidade dos anúncios

Listas de destinatários desatualizadas, inválidas ou compradas reduzem significativamente a taxa de entrega.

A má qualidade da lista aumenta:

• Rejeições definitivas
• Reclamações sobre spam
• Cancelamentos de assinatura

Melhores práticas:

• Colete endereços por meio de processos válidos de adesão voluntária.
• Remova rapidamente os destinatários inválidos.
• Limpe regularmente os destinatários inativos.
• Nunca compre listas de e-mail.

Preços de e-mail

A estrutura de preços da API de e-mail é baseada em assinatura e está disponível em vários planos. Cada plano inclui um número fixo de e-mails, sendo aplicadas taxas de excedente por cada e-mail adicional.

Para obter detalhes atualizados sobre preços, entre em contato com seu gerente de contas.

Mais informações

• Noções básicas sobre mensagens de e-mail
• Referência da Messages API