API de E-mail

/createEmailMessage está obsoleto

Novas integrações devem usar a API de Mensagens v2 — passe platforms: ["EMAIL"] e um bloco email_payload para Notify. Consulte o guia de migração.

createEmailMessage Obsoleto

Cria uma mensagem de e-mail.

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

Parâmetros do corpo da solicitação

Nome	Tipo	Obrigatório	Descrição
auth	string	Sim	Token de acesso à API do Painel de Controle da Pushwoosh.
application	string	Sim	Código do aplicativo Pushwoosh
notifications	array	Sim	Array JSON contendo os detalhes da mensagem de e-mail. Consulte a tabela Parâmetros de Notificações abaixo.

Parâmetros de notificações

Nome	Tipo	Obrigatório	Descrição
send_date	string	Sim	Define quando enviar o e-mail. Formato: YYYY-MM-DD HH:mm ou "now".
preset	string	Sim	Código de predefinição de e-mail. Copie da barra de URL do Editor de Conteúdo de E-mail no Painel de Controle da Pushwoosh.
subject	string ou object	Não	Linha de assunto do e-mail. O e-mail estará sempre no idioma do conteúdo. Se subject não contiver um idioma correspondente para content, o assunto ficará em branco.
content	string ou object	Não	O conteúdo do corpo do e-mail. Pode ser uma string para conteúdo HTML simples ou um objeto para versões localizadas.
attachments	array	Não	Os anexos do e-mail. Apenas dois anexos estão disponíveis. Cada anexo não deve exceder 1MB (codificado em base64).
list_unsubscribe	string	Não	Permite definir uma URL personalizada para o cabeçalho “Link-Unsubscribe”.
campaign	string	Não	Código da campanha para associar o e-mail a uma campanha específica.
ignore_user_timezone	boolean	Não	Se true, envia o e-mail imediatamente, ignorando os fusos horários do usuário.
timezone	string	Não	Envia o e-mail de acordo com o fuso horário do usuário. Exemplo: "America/New_York".
filter	string	Não	Envia o e-mail para usuários que correspondem a uma condição de filtro específica.
devices	array	Não	Lista de endereços de e-mail (máx. 1000) para enviar e-mails direcionados. Se usado, a mensagem é enviada apenas para esses endereços. Ignorado se o Grupo de Aplicativos for usado.
use_auto_registration	boolean	Não	Se true, registra automaticamente os e-mails do parâmetro devices.
users	array	Não	Se definido, a mensagem de e-mail será entregue apenas aos User IDs especificados (registrados via chamada /registerEmail). Não mais que 1000 User IDs em um array. Se o parâmetro “devices” for especificado, o parâmetro “users” será ignorado.
dynamic_content_placeholders	object	Não	Placeholders para conteúdo dinâmico em vez de valores de tags de dispositivo.
conditions	array	Não	Condições de segmentação usando tags. Exemplo: [["Country", "EQ", "BR"]].
from	object	Não	Especifique um nome e e-mail de remetente personalizados, substituindo o padrão nas propriedades do aplicativo.
reply-to	object	Não	Especifique um e-mail de resposta personalizado, substituindo o padrão nas propriedades do aplicativo.
bcc	array	Não	BCC (Cópia Oculta): array de endereços de e-mail que recebem uma cópia do e-mail sem que outros destinatários os vejam.
email_type	string	Não	Especifique o tipo de e-mail: "marketing" ou "transactional". Se omitido, usuários com PW_ControlGroup: true não receberão a mensagem.
email_category	string	Obrigatório quando email_type é "marketing".	Especifique um dos nomes de categoria configurados no centro de preferências de assinatura (por exemplo, Newsletter, Promocional, Atualizações de Produto).
transactionId	string	Não	Identificador único de mensagem para evitar o reenvio em caso de problemas de rede. Armazenado no lado da Pushwoosh por 5 minutos.
capping_days	integer	Não	O número de dias (máx. 30) para aplicar o limite de frequência por dispositivo. Nota: Certifique-se de que o Limite de frequência global esteja configurado no Painel de Controle.
capping_count	integer	Não	O número máximo de e-mails que podem ser enviados de um aplicativo específico para um dispositivo específico dentro de um período de capping_days. Caso a mensagem criada exceda o limite de capping_count para um dispositivo, ela não será enviada para esse dispositivo.
capping_exclude	boolean	Não	Se definido como true, este e-mail não será contado para o limite de frequência de e-mails futuros.
capping_avoid	boolean	Não	Se definido como true, o limite de frequência não será aplicado a este e-mail específico.
send_rate	integer	Não	Limite quantas mensagens podem ser enviadas por segundo para todos os usuários. Ajuda a prevenir sobrecarga no backend durante envios de alto volume.
send_rate_avoid	boolean	Não	Se definido como true, o limite de throttling não será aplicado a este e-mail específico.

Exemplo de solicitação

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // obrigatório. Token de acesso à API do Painel de Controle da Pushwoosh
    "application": "APPLICATION_CODE",  // obrigatório. Código do aplicativo Pushwoosh.
    "notifications": [{
      "send_date": "now",               // obrigatório. AAAA-MM-DD HH:mm OU 'now'
      "preset": "ERXXX-32XXX",          // obrigatório. Copie o código de predefinição de e-mail da barra de URL da
                                        //           página do Editor de Conteúdo de E-mail no Painel de Controle da Pushwoosh.
      "subject": {                      // opcional. Linha de assunto da mensagem de e-mail.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // opcional. Conteúdo do corpo do e-mail.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // opcional. Anexos de e-mail
        "name": "image.png",            //           "name" - nome do arquivo
        "content": "iVBANA...AFTkuQmwC" //           "content" - conteúdo do arquivo codificado em base64
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // opcional. Permite definir uma URL personalizada para o cabeçalho "Link-Unsubscribe"
      "campaign": "CAMPAIGN_CODE",      // opcional. Para atribuir esta mensagem de e-mail a uma campanha específica,
                                        //           adicione um código de campanha aqui.
      "ignore_user_timezone": true,     // opcional.
      "timezone": "America/New_York",   // opcional. Especifique para enviar a mensagem de acordo com
                                        //           o fuso horário definido no dispositivo do usuário.
      "filter": "FILTER_NAME",          // opcional. Envie a mensagem para usuários específicos que atendam às condições do filtro.
      "devices": [                      // opcional. Especifique endereços de e-mail para enviar mensagens de e-mail direcionadas.
        "email_address1",               //           Não mais que 1000 endereços em um array.
        "email_address2"                //           Se definido, a mensagem será enviada apenas para os endereços na
      ],                                //           lista. Ignorado se o Grupo de Aplicativos for usado.
      "use_auto_registration": true,    // opcional. Registra automaticamente os e-mails especificados no parâmetro "devices"
      "users": [                        // opcional. Se definido, a mensagem de e-mail será entregue apenas aos
        "userId1",                      //           User IDs especificados (registrados via chamada /registerEmail).
        "userId2"                       //           Não mais que 1000 User IDs em um array.
      ],                                //           Se o parâmetro "devices" for especificado,
                                        //           o parâmetro "users" será ignorado.
      "dynamic_content_placeholders": { // opcional. Placeholders para conteúdo dinâmico em vez de valores de tags de dispositivo.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // opcional. Condições de segmentação, veja a observação abaixo.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // opcional. Especifique um nome de remetente e um endereço de e-mail de remetente
        "name": "alias from",           //           para substituir o "Nome do remetente" e o "E-mail do remetente" padrão
        "email": "from-email@email.com" //           configurados nas propriedades do aplicativo.
      },
      "reply-to": {                     // opcional. Especifique um endereço de e-mail para substituir o
        "name": "alias reply to ",      //           "Responder para" padrão configurado nas propriedades do aplicativo.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // opcional. BCC: array de endereços de e-mail que recebem uma cópia sem que outros destinatários os vejam.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // opcional. "marketing" ou "transactional".
                                        // Se omitido, usuários com PW_ControlGroup: true não receberão a mensagem.
      "email_category": "category name",// obrigatório quando email_type é "marketing". Nome da categoria.
      "transactionId": "unique UUID",   // opcional. Identificador único de mensagem para evitar o reenvio
                                        //           em caso de problemas de rede. Armazenado no lado
                                        //           da Pushwoosh por 5 minutos.
      // Parâmetros de limite de frequência. Certifique-se de que o Limite de frequência global esteja configurado no Painel de Controle.
      // O limite de frequência não se aplica a mensagens transacionais.
      // Em todos os outros casos, incluindo "email_type" omitido, o limite de frequência se aplica.
      "capping_days": 30,               // opcional. Quantidade de dias para o limite de frequência (máx. 30 dias)
      "capping_count": 10,              // opcional. O número máximo de e-mails que podem ser enviados de um
                                        //           aplicativo específico para um dispositivo específico dentro de um período de 'capping_days'
                                        //           . Caso a mensagem criada exceda o
                                        //           limite 'capping_count' para um dispositivo, ela não
                                        //           será enviada para esse dispositivo.
      "capping_exclude": true,          // opcional. Se definido como true, este e-mail não
                                        //           será contado para o limite de frequência de e-mails futuros.
      "capping_avoid": true,            // opcional. Se definido como true, o limite de frequência não será aplicado a
                                        //           este e-mail específico.
      "send_rate": 100,                 // opcional. Limite de throttling.
                                        //           Limite quantas mensagens podem ser enviadas por segundo para todos os usuários.
                                        //           Ajuda a prevenir sobrecarga no backend durante envios de alto volume.
      "send_rate_avoid": true,          // opcional. Se definido como true, o limite de throttling não será aplicado a
                                        //           este e-mail específico.
    }]
  }
}

Exemplos de resposta

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

403

{
  "status_code": 403,
  "status_message": "As restrições de token proíbem esta operação",
  "response": null
}

Condições de tag

Cada condição de tag é um array como [tagName, operator, operand] onde

• tagName: nome de uma tag
• operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
• operand: string | integer | array | date

Descrição do operando

• EQ: o valor da tag é igual ao operando;
• IN: o valor da tag cruza com o operando (o operando deve ser sempre um array);
• NOTEQ: o valor da tag não é igual a um operando;
• NOTIN: o valor da tag não cruza com o operando (o operando deve ser sempre um array);
• GTE: o valor da tag é maior ou igual ao operando;
• LTE: o valor da tag é menor ou igual ao operando;
• BETWEEN: o valor da tag é maior ou igual ao valor mínimo do operando, mas menor ou igual ao valor máximo do operando (o operando deve ser sempre um array).

Tags de string

Operadores válidos: EQ, IN, NOTEQ, NOTIN
Operandos válidos:

• EQ, NOTEQ: o operando deve ser uma string;
• IN, NOTIN: o operando deve ser um array de strings como ["valor 1", "valor 2", "valor N"];

Tags de inteiro

Operadores válidos: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Operandos válidos:

• EQ, NOTEQ, GTE, LTE: o operando deve ser um inteiro;
• IN, NOTIN: o operando deve ser um array de inteiros como [valor 1, valor 2, valor N];
• BETWEEN: o operando deve ser um array de inteiros como [valor_min, valor_max].

Tags de data

Operadores válidos: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Operandos válidos:

• "YYYY-MM-DD 00:00" (string)
• unix timestamp 1234567890 (integer)
• "N days ago" (string) para os operadores EQ, BETWEEN, GTE, LTE

Tags booleanas

Operadores válidos: EQ
Operandos válidos: 0, 1, true, false

Tags de lista

Operadores válidos: IN
Operandos válidos: o operando deve ser um array de strings como ["valor 1", "valor 2", "valor N"].

Perigo

Lembre-se de que os parâmetros “filter” e “conditions” não devem ser usados juntos.
Além disso, ambos serão ignorados se o parâmetro “devices” for usado na mesma solicitação.

Nota

Tags de País e Idioma

O valor da tag de Idioma é um código de duas letras minúsculas de acordo com a ISO-639-1
O valor da tag de País é um código de duas letras MAIÚSCULAS de acordo com a ISO_3166-2
Por exemplo, para enviar uma notificação push para assinantes de língua portuguesa no Brasil, você precisará especificar a seguinte condição: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Registra o endereço de e-mail para o aplicativo.

POST https://api.pushwoosh.com/json/1.3/registerEmail

Cabeçalhos da solicitação

Nome	Obrigatório	Valor	Descrição
Authorization	Sim	Token XXXX	Token de Dispositivo da API para acessar a API de Dispositivo. Substitua XXXX pelo seu token real da API de Dispositivo.

Corpo da solicitação

Nome	Tipo	Descrição
application*	string	Código do aplicativo Pushwoosh
email*	string	Endereço de e-mail.
language	string	Localidade de idioma do dispositivo. Deve ser um código de duas letras minúsculas de acordo com o padrão ISO-639-1.
userId	string	User ID para associar ao endereço de e-mail.
tz_offset	integer	Deslocamento de fuso horário em segundos.
tags	object	Valores de tag para atribuir ao dispositivo registrado.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

210

{
  "status_code": 210,
  "status_message": "este hwid (e-mail) está na lista negra",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Argumento obrigatório ausente: email",
  "response": null
}

403

{
  "status_code": 403,
  "status_message": "As restrições de token proíbem esta operação",
  "response": null
}

500

{
  "status_code": 500,
  "status_message": "Erro interno do servidor",
  "response": null
}

Exemplo

{
  "request": {
    "application": "APPLICATION_CODE",   // obrigatório. Código do aplicativo Pushwoosh.
    "email":"email@domain.com",          // obrigatório. Endereço de e-mail a ser registrado.
    "language": "en",                    // opcional. Localidade do idioma.
    "userId": "userId",                  // opcional. User ID para associar ao endereço de e-mail.
    "tz_offset": 3600,                   // opcional. Deslocamento de fuso horário em segundos.
    "tags": {                            // opcional. Valores de tag para definir para o dispositivo registrado.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // define a lista de valores para Tags do tipo Lista
       "DateTag": "2024-10-02 22:11",    // observe que o horário deve estar em UTC
       "BooleanTag": true                // valores válidos são: true, false
    }
  }
}

Códigos de resposta

A API pública retorna o resultado em status_code. Use a tabela abaixo para decidir se uma chamada com falha deve ser repetida.

status_code	Significado	Tentar novamente?
200	Sucesso — o endereço de e-mail foi registrado.	Não — concluído.
210	Erro de argumento/validação — a solicitação foi entendida, mas rejeitada (endereço na lista negra, e-mail inválido ou descartável, plataforma errada para o plano da conta). Veja mensagens de erro 210 abaixo.	Não — a mesma solicitação retorna o mesmo 210. Registre o endereço e pule-o.
400	Solicitação malformada — JSON inválido ou um campo obrigatório ausente.	Não — corrija a solicitação, não a repita.
403	Proibido — token da API de Dispositivo inválido ou restrito.	Não — corrija a autorização.
500	Erro interno do servidor — problema temporário de infraestrutura ou tempo limite.	Sim, com recuo exponencial — o único caso transitório.

Dica

Tente novamente apenas respostas 500, usando recuo exponencial — é o único caso transitório. Um 210, 400 ou 403 é final: o servidor entendeu sua solicitação e a rejeitou, então repeti-la sem alterações retorna o mesmo resultado. Em vez disso, registre o endereço (para 210) ou corrija a solicitação/token (para 400/403).

Mensagens de erro 210

Uma resposta 210 carrega o motivo específico em status_message.

status_message	Significado
this hwid (email) is blacklisted	O endereço está na lista de supressão após um bounce permanente (hard) e não será registrado novamente.
hwid (email) is invalid / has invalid semantic	O endereço falha na validação.
hwid (email) is empty	Nenhum endereço foi fornecido.
hwid (email) has invalid count of parts	Faltando ou com @ extra.
hwid (email) has invalid local part	A parte antes de @ é inválida.
hwid (email) has invalid domain part	A parte do domínio é inválida.
hwid (email) has disposable domain	O endereço usa um domínio de e-mail descartável/temporário (por exemplo, 10minutemail).
hwid is not valid	O próprio hwid está malformado.
only email platform allowed for Email Only subscription	A conta está em um plano Somente E-mail e não pode registrar dispositivos que não sejam de e-mail.

Nota

Apenas bounces permanentes (hard) adicionam um endereço à lista negra. Bounces soft e reclamações de spam não bloqueiam registerEmail — apenas this hwid (email) is blacklisted reflete a supressão.

deleteEmail

Remove o endereço de e-mail da sua base de usuários.

POST https://api.pushwoosh.com/json/1.3/deleteEmail

Cabeçalhos da solicitação

Nome	Obrigatório	Valor	Descrição
Authorization	Sim	Token XXXX	Token de Dispositivo da API para acessar a API de Dispositivo. Substitua XXXX pelo seu token real da API de Dispositivo.

Corpo da solicitação

Nome	Tipo	Descrição
application	string	Código do aplicativo Pushwoosh
email	string	Endereço de e-mail usado na solicitação /registerEmail.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Exemplo

{
  "request": {
    "application": "APPLICATION_CODE",  // obrigatório. Código do aplicativo Pushwoosh
    "email": "email@domain.com"         // obrigatório. E-mail a ser excluído dos assinantes do aplicativo.
  }
}

setEmailTags

Define os valores das tags para o endereço de e-mail.

POST https://api.pushwoosh.com/json/1.3/setEmailTags

Cabeçalhos da solicitação

Nome	Obrigatório	Valor	Descrição
Authorization	Sim	Token XXXX	Token de Dispositivo da API para acessar a API de Dispositivo. Substitua XXXX pelo seu token real da API de Dispositivo.

Corpo da solicitação

Nome	Tipo	Descrição
application	string	Código do aplicativo Pushwoosh
email	string	Endereço de e-mail.
tags	object	Objeto JSON de tags a serem definidas, envie ‘null’ para remover o valor.
userId	string	User ID associado ao endereço de e-mail.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

Exemplo

{
  "request": {
    "email": "email@domain.com",                  // obrigatório. Endereço de e-mail para o qual definir as tags.
    "application": "APPLICATION_CODE",            // obrigatório. Código do aplicativo Pushwoosh.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // horário em UTC
      "BooleanTag": true                          // valores válidos são: true, false
    },
    "userId": "userId"                            // opcional. User ID associado ao endereço de e-mail.
  }
}

Nota

Para outros tipos de dispositivo, será retornado 200 OK, embora as tags não sejam salvas.

Cuidado

Por favor, evite definir mais de 50 valores de tag em uma única solicitação /setEmailTags.

registerEmailUser

Associa um User ID externo a um endereço de e-mail especificado.

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

Nota

Por favor, note que este método não registra um endereço de e-mail em sua base de usuários; ele deve ser usado apenas para atribuir User IDs a endereços de e-mail que já foram registrados pela solicitação /registerEmail.

Pode ser usado na chamada da API /createEmailMessage (o parâmetro ‘users’).

Cabeçalhos da solicitação

Nome	Obrigatório	Valor	Descrição
Authorization	Sim	Token XXXX	Token de Dispositivo da API para acessar a API de Dispositivo. Substitua XXXX pelo seu token real da API de Dispositivo.

Corpo da solicitação

Nome	Tipo	Descrição
application*	string	Código do aplicativo Pushwoosh
email*	string	Endereço de e-mail.
userId*	string	User ID para associar ao endereço de e-mail.
tz_offset	integer	Deslocamento de fuso horário em segundos.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

403

{
  "status_code": 403,
  "status_message": "Forbidden."
}

Exemplo

{
  "request": {
    "application": "APPLICATION_CODE", // obrigatório. Código do aplicativo Pushwoosh.
    "email": "email@domain.com",       // obrigatório. Endereço de e-mail do usuário.
    "userId": "userId",                // obrigatório. User ID para associar ao endereço de e-mail.
    "tz_offset": 3600                  // opcional. Deslocamento de fuso horário em segundos.
  }
}

Nota

Para recuperar dados sobre soft bounces, hard bounces e reclamações de e-mail, incluindo a data, o endereço de e-mail e o motivo de cada bounce, use o método BouncedEmails.