Newsletter – API v1 and v2

Explorando a Newsletter API v1 e v2

Neste guia, vamos explorar como a Newsletter API v1 e v2 funcionam, suas funcionalidades e como integrá-las em diferentes contextos. A Newsletter API é uma ferramenta poderosa que permite a interação com sistemas de gerenciamento de assinantes, oferecendo métodos para gerenciar e automatizar a comunicação via e-mail.

O que são as versões da Newsletter API?

A Newsletter API é dividida em duas versões: v1 e v2. Enquanto a versão 1 ainda é suportada, a versão 2 traz um nível de flexibilidade e recursos que a tornam a opção recomendada. Portanto, se você ainda está utilizando a v1, é aconselhável considerar a migração para conseguir usufruir de todas as melhorias e opções que a v2 oferece.

Ambas as versões requerem a instalação de um complemento gratuito, que pode ser facilmente baixado pela página da sua conta.

Como funciona a autenticação?

Um dos pontos importantes a serem destacados é a autenticação. A maioria das chamadas de API requer uma chave de autenticação, essencial para garantir que somente usuários qualificados possam acessar e manipular os dados dos assinantes. Essa medida de segurança é crucial em um mundo onde dados pessoais e informações sensíveis estão em constante circulação.

Adicionando um assinante

Quando é necessário adicionar um novo assinante, como por exemplo, sempre que um novo contato é registrado em um CRM, você deve usar o endpoint de assinantes com o método POST. O formato esperado para a requisição é um objeto JSON, onde o mais importante a ser incluído é o endereço de e-mail do assinante.

Um detalhe importante: o método de adição não envia e-mails de ativação ou boas-vindas. Ele apenas insere o assinante na base de dados e retorna todos os dados do assinante, acompanhados de um ID único. Também é importante notar que, ao usar esse método, não são realizados checagens de spam, pois pressupõe-se que a origem dos dados do outro sistema já é confiável.

Atualizando informações de um assinante

Se a sua necessidade envolve atualizar dados de um assinante já existente, você deve utilizar o endpoint de assinantes com o método PUT. É necessário fornecer o ID do assinante ou o endereço de e-mail para que a operação seja bem-sucedida. Essa operação permite modificar diversos campos de dados do assinante.

Por exemplo, se você coletou novos dados em uma pesquisa e deseja atualizá-los na lista de assinantes, isso pode ser feito de maneira rápida e eficaz utilizando essa funcionalidade.

Adicionando ou atualizando um assinante em uma única chamada

Se você deseja tanto adicionar quanto atualizar um assinante, a API permite isso com o uso do método PUT. Essa funcionalidade é útil, por exemplo, ao sincronizar dados entre um CRM e a sua lista de e-mails, evitando duplicidades e garantindo que as informações estejam sempre atualizadas.

Gerenciando status de assinantes

O status do assinante é fundamental para determinar se ele pode ou não receber newsletters. Se não for especificado, o sistema automaticamente define como “confirmado”. No entanto, se houver a necessidade de alterar esse status, deve-se enviar a informação correspondente na requisição.

Com isso, a API não apenas permite que você gerencie quem recebe suas comunicações, mas também considera a integridade dos dados fornecidos por sistemas externos.

Trabalhando com listas de assinantes

Em diversas situações, pode haver a necessidade de adicionar um assinante a listas específicas, como quando uma ação externa é realizada. Para isso, o método PUT do endpoint de assinantes deve ser utilizado novamente. Através dele, você pode indicar quais listas um assinante deve ou não ser adicionado.

Isso pode ser particularmente útil para campanhas direcionadas ou quando um cliente opta por receber comunicações sobre um serviço específico.

Deletando assinantes

Se a decisão é remover completamente um assinante do sistema, o método DELETE no endpoint de assinantes será seu aliado. Essa operação remove todos os dados de maneira irreversível, incluindo estatísticas sobre interações com newsletters anteriores.

Entretanto, se o objetivo for apenas impedir o envio de novos e-mails a um assinante, mudá-lo para o status “cancelado” seria mais apropriado, pois mantém os dados do assinante no sistema, mas bloqueia qualquer comunicação futura.

Iniciando processos de assinatura

A API também permite que você inicie processos de assinatura de forma mais flexível, não requerendo uma chave API para isso. Essa funcionalidade é essencial para cenários nos quais os assinantes se inscrevem através de outros canais, como aplicativos.

Ao utilizar o endpoint de assinaturas com o método POST, você pode fazer com que todo o processo de assinatura, incluindo checagens de spam e envio de e-mails de ativação, ocorra automaticamente.

Cancelamento de assinatura

Embora o cancelamento não possa ser iniciado diretamente pela API nesse momento, um link de cancelamento deve ser incluído nas newsletters, permitindo que os usuários iniciem esse processo com facilidade. A mudança de status para “cancelado” pode ser feita via chamada da API, mas isso não deve ser feito de maneira pública, garantindo assim a segurança dos dados.

Mudando dados de perfil do assinante

Embora atualmente não seja possível que assinantes mudem seus dados de perfil de maneira pública, você pode implementar uma solução em nível de servidor que utilize o endpoint de assinantes. Essa abordagem pode oferecer aos usuários um controle mais fácil sobre suas informações pessoais.

Listando listas de assinatura

Para obter uma visão clara das listas de assinatura configuradas, o endpoint de listas deve ser utilizado com o método GET. Essa chamada retornará todas as listas, sejam públicas ou privadas, com base na chave de autenticação fornecida.

Acessando newsletters enviadas

Se você precisar de informações sobre newsletters enviadas recentemente, o endpoint de newsletters é a solução. Novamente, essa chamada requer uma chave de API para acessar os dados completos, com a resposta normalmente retornando as últimas 10 newsletters.

Lembre-se de que esse serviço só disponibiliza newsletters que foram efetivamente enviadas e não abrange aquelas em estado de rascunho ou programadas.

Testando a API em ambientes não seguros

Caso você deseje testar a API em ambientes locais sem HTTPS, é possível modificar o arquivo wp-config.php para permitir requisições não seguras. No entanto, essa prática não é recomendada em ambientes de produção, pois compromete a segurança da transmissão de dados.

Para isso, você pode adicionar a seguinte linha de código no seu arquivo:
php
define ('NEWSLETTER_REST_ALLOW_NON_HTTPS_REQUEST', true);

Conclusão

A Newsletter API v1 e v2 oferece um conjunto robusto de funcionalidades que facilitam a gestão de assinantes e a automação de processos de e-mail marketing. Seja você um desenvolvedor ou um administrador de marketing, entender como utilizar esses endpoints pode abrir portas para integrar sua plataforma de forma eficiente e eficaz. Não se esqueça de aproveitar as atualizações e melhorias disponíveis na versão mais recente para garantir que você está utilizando a tecnologia mais avançada disponível.