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.

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 sempre estará 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 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 de 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 tag 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 exclusivo 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 a sobrecarga do 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",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, users with PW_ControlGroup: true will not receive the message.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

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: 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)
• 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 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 para atribuir ao dispositivo registrado.

200

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

Exemplo

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

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",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

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 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",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

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 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", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}

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.