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 da aplicação Pushwoosh
notifications	array	Sim	Array JSON contendo detalhes da mensagem de e-mail. Consulte a tabela Parâmetros de Notificações abaixo.

Dica

Passe um cabeçalho X-Request-ID para correlacionar a mensagem criada com sua solicitação para rastreamento de ponta a ponta — consulte ID da Solicitação.

Parâmetros de notificações

Nome	Tipo	Obrigatório	Descrição
send_date	string	Sim	Define quando enviar o e-mail. Formato: AAAA-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 o subject não contiver um idioma correspondente para o content, o assunto ficará vazio.
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áximo de 1000) para enviar e-mails direcionados. Se usado, a mensagem é enviada apenas para esses endereços. Ignorado se o Grupo de Aplicações 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 IDs de Usuário especificados (registrados via chamada /registerEmail). Não mais que 1000 IDs de usuário em um array. Se o parâmetro “devices” for especificado, o parâmetro “users” será ignorado.
dynamic_content_placeholders	object	Não	Espaços reservados 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 de remetente e e-mail personalizados, substituindo o padrão nas propriedades da aplicação.
reply-to	object	Não	Especifique um e-mail de resposta personalizado, substituindo o padrão nas propriedades da aplicação.
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 de mensagem único 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áximo 30) para aplicar o limite de frequência por dispositivo. Nota: Certifique-se de que o Limite de frequência global está 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 a sobrecarga do backend durante envios de alto volume.
send_rate_avoid	boolean	Não	Se definido como verdadeiro, 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 da aplicação 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 Aplicações for usado.
      "use_auto_registration": true,    // opcional. Registre automaticamente os e-mails especificados no parâmetro "devices"
      "users": [                        // opcional. Se definido, a mensagem de e-mail será entregue apenas aos
        "userId1",                      //           IDs de usuário especificados (registrados via chamada /registerEmail).
        "userId2"                       //           Não mais que 1000 IDs de usuário em um array.
      ],                                //           Se o parâmetro "devices" for especificado,
                                        //           o parâmetro "users" será ignorado.
      "dynamic_content_placeholders": { // opcional. Espaços reservados 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 do 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 da aplicação.
      },
      "reply-to": {                     // opcional. Especifique um endereço de e-mail para substituir o
        "name": "alias reply to ",      //           "Responder para" padrão configurado nas propriedades da aplicação.
        "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 de mensagem único 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 está 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áximo 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 verdadeiro, este e-mail não
                                        //           será contado para o limite de frequência de e-mails futuros.
      "capping_avoid": true,            // opcional. Se definido como verdadeiro, 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 a sobrecarga do backend durante envios de alto volume.
      "send_rate_avoid": true,          // opcional. Se definido como verdadeiro, 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": "Token restrictions forbid this operation",
  "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 | data

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:

• "AAAA-MM-DD 00:00" (string)
• timestamp unix 1234567890 (inteiro)
• "N dias atrás" (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 da aplicação 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	ID de Usuário para associar ao endereço de e-mail.
tz_offset	integer	Deslocamento de fuso horário em segundos.
tags	object	Valores de tag a serem atribuídos ao dispositivo registrado.

200

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

210

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

403

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

500

{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}

Exemplo

{
  "request": {
    "application": "APPLICATION_CODE",   // obrigatório. Código da aplicação Pushwoosh.
    "email":"email@domain.com",          // obrigatório. Endereço de e-mail a ser registrado.
    "language": "en",                    // opcional. Localidade de idioma.
    "userId": "userId",                  // opcional. ID de Usuário para associar ao endereço de e-mail.
    "tz_offset": 3600,                   // opcional. Deslocamento de fuso horário em segundos.
    "tags": {                            // opcional. Valores de tag a serem definidos 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). Consulte as 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	@ ausente ou 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 da aplicação 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 da aplicação Pushwoosh
    "email": "email@domain.com"         // obrigatório. E-mail a ser excluído dos assinantes do aplicativo.
  }
}

setEmailTags

Define valores de tag 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 da aplicação 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	ID de Usuário 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 da aplicação 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. ID de Usuário 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

Evite definir mais de 50 valores de tag em uma única solicitação /setEmailTags.

registerEmailUser

Associa um ID de Usuário externo a um endereço de e-mail especificado.

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

Nota

Observe 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 IDs de usuário 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 da aplicação Pushwoosh
email*	string	Endereço de e-mail.
userId*	string	ID de Usuário 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 da aplicação Pushwoosh.
    "email": "email@domain.com",       // obrigatório. Endereço de e-mail do usuário.
    "userId": "userId",                // obrigatório. ID de Usuário para associar ao endereço de e-mail.
    "tz_offset": 3600                  // opcional. Deslocamento de fuso horário em segundos.
  }
}

Nota

Para recuperar dados sobre bounces soft, bounces hard 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.