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 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. 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 o subject não contiver um idioma correspondente para o 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á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 User IDs 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	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 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	CCO (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".
email_category	string	Obrigatório quando email_type é "marketing".	Especifique um dos nomes de categoria configurados no centro de preferências de inscrição (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 de 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 uma aplicação específica 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	Limita quantas mensagens podem ser enviadas por segundo para todos os usuários. Ajuda a prevenir 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".
      "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.
      "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 número inteiro

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

• EQ, NOTEQ, GTE, LTE: o operando deve ser um número 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 os operadores EQ, BETWEEN, GTE, LTE

Tags de booleano

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 a aplicação.

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	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 a serem atribuídos 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 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	User ID 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 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 na 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	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", // 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, endereço de e-mail e o motivo de cada bounce, use o método BouncedEmails.