API de E-mail

createEmailMessage

Cria uma mensagem de e-mail.

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

Parâmetros do corpo da requisição

Nome	Tipo	Obrigatório	Descrição
auth	string	Sim	Token de acesso da 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. Veja 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 do preset 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á 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 dos usuários.
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 Aplicação 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 da aplicação.
reply-to	object	Não	Especifique um e-mail de resposta (reply-to) personalizado, substituindo o padrão nas propriedades da aplicação.
transactionId	string	Não	Identificador único da mensagem para evitar 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 frequency capping por dispositivo. Nota: Certifique-se de que o Global frequency capping 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 capping de futuros e-mails.
capping_avoid	boolean	Não	Se definido como true, o capping não será aplicado a este e-mail específico.
send_rate	integer	Não	Limita 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 requisição

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // obrigatório. Token de acesso da API do Painel de Controle da Pushwoosh
    "application": "APPLICATION_CODE",  // obrigatório. Código da aplicação Pushwoosh.
    "notifications": [{
      "send_date": "now",               // obrigatório. YYYY-MM-DD HH:mm OU 'now'
      "preset": "ERXXX-32XXX",          // obrigatório. Copie o código do preset 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 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. Envia a mensagem para usuários específicos que atendem à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ção 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 observação abaixo.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // opcional. Especifique um nome de remetente e endereço de e-mail de remetente
        "name": "alias from",           //           para substituir o "From name" e "From email" 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 ",      //           "Reply to" padrão configurado nas propriedades da aplicação.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // opcional. Identificador único da mensagem para evitar reenvio
                                        //           em caso de problemas de rede. Armazenado no lado
                                        //           da Pushwoosh por 5 minutos.
      // Parâmetros de frequency capping. Certifique-se de que o Global frequency capping esteja configurado no Painel de Controle.
      "capping_days": 30,               // opcional. Quantidade de dias para frequency capping (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
                                        //           '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": true,          // opcional. Se definido como true, este e-mail não será
                                        //           contado para o capping de futuros e-mails.
      "capping_avoid": true,            // opcional. Se definido como true, o capping não será aplicado a
                                        //           este e-mail específico.
      "send_rate": 100,                 // opcional. Limite de throttling.
                                        //           Limita 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": "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 | date

Descrição do operando

• EQ: valor da tag é igual ao operando;
• IN: valor da tag intercepta o operando (o operando deve ser sempre um array);
• NOTEQ: valor da tag não é igual a um operando;
• NOTIN: valor da tag não intercepta o operando (o operando deve ser sempre um array);
• GTE: valor da tag é maior ou igual ao operando;
• LTE: valor da tag é menor ou igual ao operando;
• BETWEEN: 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)
• timestamp unix 1234567890 (inteiro)
• "N days ago" (string) para 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 requisição.

Nota

Tags de País e Idioma

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

registerEmail

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

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

Cabeçalhos da requisição

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

Corpo da requisição

Nome	Tipo	Descrição
application*	string	Código da aplicação Pushwoosh
email*	string	Endereço de e-mail.
language	string	Localidade do 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 do fuso horário em segundos.
tags	object	Valores de tag para atribuir ao dispositivo registrado.

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. 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 do 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 a hora deve estar em UTC
       "BooleanTag": true                // valores válidos são: true, false
    }
  }
}

deleteEmail

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

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

Cabeçalhos da requisição

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

Corpo da requisição

Nome	Tipo	Descrição
application	string	Código da aplicação Pushwoosh
email	string	Endereço de e-mail usado na requisiçã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 para excluir dos assinantes do app.
  }
}

setEmailTags

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

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

Cabeçalhos da requisição

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

Corpo da requisiçã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 para definir, 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 definir 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",              // hora 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 dispositivos será retornado 200 OK, embora as tags não sejam salvas.

Cuidado

Por favor, evite definir mais de 50 valores de tags em uma única requisiçã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

Observe que este método não registra um endereço de e-mail na 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 requisição /registerEmail.

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

Cabeçalhos da requisição

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

Corpo da requisição

Nome	Tipo	Descrição
application*	string	Código da aplicação Pushwoosh
email*	string	Endereço de e-mail.
userId*	string	User ID para associar ao endereço de e-mail.
tz_offset	integer	Deslocamento do 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. User ID para associar ao endereço de e-mail.
    "tz_offset": 3600                  // opcional. Deslocamento do fuso horário em segundos.
  }
}

Nota

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