API de Email

/createEmailMessage está obsoleto

Las nuevas integraciones deberían usar la API de Mensajería v2 — pase platforms: ["EMAIL"] y un bloque email_payload a Notify. Consulte la guía de migración.

createEmailMessage Obsoleto

Crea un mensaje de correo electrónico.

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

Parámetros del cuerpo de la solicitud

Nombre	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh
notifications	array	Sí	Array JSON que contiene los detalles del mensaje de correo electrónico. Consulte la tabla de Parámetros de Notificaciones a continuación.

Consejo

Pase una cabecera X-Request-ID para correlacionar el mensaje creado con su solicitud para un seguimiento de extremo a extremo — consulte ID de Solicitud.

Parámetros de notificaciones

Nombre	Tipo	Requerido	Descripción
send_date	string	Sí	Define cuándo enviar el correo electrónico. Formato: YYYY-MM-DD HH:mm o "now".
preset	string	Sí	Código de preset de email. Cópielo de la barra de URL del Editor de Contenido de Email en el Panel de Control de Pushwoosh.
subject	string o object	No	Línea de asunto del correo electrónico. El correo electrónico siempre estará en el idioma del contenido. Si subject no contiene un idioma que coincida con content, el asunto estará vacío.
content	string o object	No	El contenido del cuerpo del correo electrónico. Puede ser una cadena para contenido HTML simple o un objeto para versiones localizadas.
attachments	array	No	Los archivos adjuntos del correo electrónico. Solo se permiten dos archivos adjuntos. Cada archivo adjunto no debe exceder 1MB (codificado en base64).
list_unsubscribe	string	No	Permite establecer una URL personalizada para la cabecera “Link-Unsubscribe”.
campaign	string	No	Código de campaña para asociar el correo electrónico con una campaña específica.
ignore_user_timezone	boolean	No	Si es true, envía el correo electrónico inmediatamente, ignorando las zonas horarias del usuario.
timezone	string	No	Envía el correo electrónico según la zona horaria del usuario. Ejemplo: "America/New_York".
filter	string	No	Envía el correo electrónico a los usuarios que coinciden con una condición de filtro específica.
devices	array	No	Lista de direcciones de correo electrónico (máximo 1000) para enviar correos electrónicos dirigidos. Si se utiliza, el mensaje se envía solo a estas direcciones. Se ignora si se utiliza el Grupo de Aplicaciones.
use_auto_registration	boolean	No	Si es true, registra automáticamente los correos electrónicos del parámetro devices.
users	array	No	Si se establece, el mensaje de correo electrónico solo se entregará a los ID de Usuario especificados (registrados a través de la llamada /registerEmail). No más de 1000 ID de usuario en un array. Si se especifica el parámetro “devices”, el parámetro “users” será ignorado.
dynamic_content_placeholders	object	No	Marcadores de posición para contenido dinámico en lugar de los valores de las etiquetas del dispositivo.
conditions	array	No	Condiciones de segmentación usando etiquetas. Ejemplo: [["Country", "EQ", "BR"]].
from	object	No	Especifique un nombre de remitente y un correo electrónico personalizados, anulando el predeterminado en las propiedades de la aplicación.
reply-to	object	No	Especifique un correo electrónico de respuesta personalizado, anulando el predeterminado en las propiedades de la aplicación.
bcc	array	No	CCO (Copia de Carbón Oculta): array de direcciones de correo electrónico que reciben una copia del correo electrónico sin que otros destinatarios las vean.
email_type	string	No	Especifique el tipo de correo electrónico: "marketing" o "transactional". Si se omite, el mensaje se trata como transaccional y se entrega a todos, incluido el grupo de control. Los mensajes de marketing no se entregan a los miembros del grupo de control.
email_category	string	Requerido cuando email_type es "marketing".	Especifique uno de los nombres de categoría configurados en el centro de preferencias de suscripción (por ejemplo, Newsletter, Promocional, Actualizaciones de Producto).
transactionId	string	No	Identificador de mensaje único para evitar el reenvío en caso de problemas de red. Se almacena en el lado de Pushwoosh durante 5 minutos.
capping_days	integer	No	El número de días (máximo 30) para aplicar la limitación de frecuencia por dispositivo. Nota: Asegúrese de que la limitación de frecuencia global esté configurada en el Panel de Control.
capping_count	integer	No	El número máximo de correos electrónicos que se pueden enviar desde una aplicación específica a un dispositivo particular dentro de un período de capping_days. En caso de que el mensaje creado exceda el límite de capping_count para un dispositivo, no se enviará a ese dispositivo.
capping_exclude	boolean	No	Si se establece en true, este correo electrónico no se contará para la limitación de frecuencia de futuros correos electrónicos.
capping_avoid	boolean	No	Si se establece en true, la limitación de frecuencia no se aplicará a este correo electrónico específico.
send_rate	integer	No	Limita cuántos mensajes se pueden enviar por segundo a todos los usuarios. Ayuda a prevenir la sobrecarga del backend durante envíos de gran volumen.
send_rate_avoid	boolean	No	Si se establece en true, el límite de throttling no se aplicará a este correo electrónico específico.

Ejemplo de solicitud

{
  "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, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "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.
    }]
  }
}

Ejemplos de respuesta

200

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

403

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

Condiciones de etiquetas

Cada condición de etiqueta es un array como [tagName, operator, operand] donde

• tagName: nombre de una etiqueta
• operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
• operand: string | integer | array | date

Descripción del operando

• EQ: el valor de la etiqueta es igual al operando;
• IN: el valor de la etiqueta se cruza con el operando (el operando siempre debe ser un array);
• NOTEQ: el valor de la etiqueta no es igual a un operando;
• NOTIN: el valor de la etiqueta no se cruza con el operando (el operando siempre debe ser un array);
• GTE: el valor de la etiqueta es mayor o igual que el operando;
• LTE: el valor de la etiqueta es menor o igual que el operando;
• BETWEEN: el valor de la etiqueta es mayor o igual que el valor mínimo del operando pero menor o igual que el valor máximo del operando (el operando siempre debe ser un array).

Etiquetas de cadena (String)

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

• EQ, NOTEQ: el operando debe ser una cadena;
• IN, NOTIN: el operando debe ser un array de cadenas como ["valor 1", "valor 2", "valor N"];

Etiquetas de entero (Integer)

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

• EQ, NOTEQ, GTE, LTE: el operando debe ser un entero;
• IN, NOTIN: el operando debe ser un array de enteros como [valor 1, valor 2, valor N];
• BETWEEN: el operando debe ser un array de enteros como [valor_min, valor_max].

Etiquetas de fecha (Date)

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

• "YYYY-MM-DD 00:00" (cadena)
• marca de tiempo unix 1234567890 (entero)
• "N days ago" (cadena) para los operadores EQ, BETWEEN, GTE, LTE

Etiquetas booleanas (Boolean)

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

Etiquetas de lista (List)

Operadores válidos: IN
Operandos válidos: el operando debe ser un array de cadenas como ["valor 1", "valor 2", "valor N"].

Peligro

Recuerde que los parámetros “filter” y “conditions” no deben usarse juntos.
Además, ambos serán ignorados si el parámetro “devices” se utiliza en la misma solicitud.

Nota

Etiquetas de País e Idioma

El valor de la etiqueta de idioma es un código de dos letras en minúsculas según ISO-639-1
El valor de la etiqueta de país es un código de dos letras en MAYÚSCULAS según ISO_3166-2
Por ejemplo, para enviar una notificación push a suscriptores de habla portuguesa en Brasil, deberá especificar la siguiente condición: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Registra la dirección de correo electrónico para la aplicación.

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

Cabeceras de la solicitud

Nombre	Requerido	Valor	Descripción
Authorization	Sí	Token XXXX	Token de Dispositivo de la API para acceder a la API de Dispositivos. Reemplace XXXX con su token real de la API de Dispositivos.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
application*	string	Código de aplicación de Pushwoosh
email*	string	Dirección de correo electrónico.
language	string	Localización de idioma del dispositivo. Debe ser un código de dos letras en minúsculas según el estándar ISO-639-1.
userId	string	ID de Usuario para asociar con la dirección de correo electrónico.
tz_offset	integer	Desplazamiento de la zona horaria en segundos.
tags	object	Valores de etiquetas para asignar al 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
}

Ejemplo

{
  "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
    }
  }
}

Códigos de respuesta

La API pública devuelve el resultado en status_code. Utilice la siguiente tabla para decidir si una llamada fallida debe reintentarse.

status_code	Significado	¿Reintentar?
200	Éxito — la dirección de correo electrónico está registrada.	No — hecho.
210	Error de argumento/validación — la solicitud fue entendida pero rechazada (dirección en lista negra, correo electrónico no válido o desechable, plataforma incorrecta para el plan de la cuenta). Consulte los mensajes de error 210 a continuación.	No — la misma solicitud devuelve el mismo 210. Registre la dirección y sáltela.
400	Solicitud mal formada — JSON no válido o un campo requerido faltante.	No — corrija la solicitud, no la repita.
403	Prohibido — token de la API de Dispositivos no válido o restringido.	No — corrija la autorización.
500	Error interno del servidor — problema temporal de infraestructura o tiempo de espera.	Sí, con retroceso exponencial — el único caso transitorio.

Consejo

Reintente solo las respuestas 500, usando retroceso exponencial — es el único caso transitorio. Un 210, 400 o 403 es final: el servidor entendió su solicitud y la rechazó, por lo que repetirla sin cambios devuelve el mismo resultado. En su lugar, registre la dirección (para 210) o corrija la solicitud/token (para 400/403).

Mensajes de error 210

Una respuesta 210 lleva la razón específica en status_message.

status_message	Significado
this hwid (email) is blacklisted	La dirección está en la lista de supresión después de un rebote permanente (duro) y no se volverá a registrar.
hwid (email) is invalid / has invalid semantic	La dirección no pasa la validación.
hwid (email) is empty	No se proporcionó ninguna dirección.
hwid (email) has invalid count of parts	Falta o sobra un @.
hwid (email) has invalid local part	La parte antes de @ no es válida.
hwid (email) has invalid domain part	La parte del dominio no es válida.
hwid (email) has disposable domain	La dirección utiliza un dominio de correo electrónico desechable/temporal (por ejemplo, 10minutemail).
hwid is not valid	El hwid en sí está mal formado.
only email platform allowed for Email Only subscription	La cuenta tiene un plan de Solo Email y no puede registrar dispositivos que no sean de correo electrónico.

Nota

Solo los rebotes permanentes (duros) añaden una dirección a la lista negra. Los rebotes suaves y las quejas de spam no bloquean registerEmail — solo this hwid (email) is blacklisted refleja la supresión.

deleteEmail

Elimina la dirección de correo electrónico de su base de usuarios.

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

Cabeceras de la solicitud

Nombre	Requerido	Valor	Descripción
Authorization	Sí	Token XXXX	Token de Dispositivo de la API para acceder a la API de Dispositivos. Reemplace XXXX con su token real de la API de Dispositivos.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
application	string	Código de aplicación de Pushwoosh
email	string	Dirección de correo electrónico utilizada en la solicitud /registerEmail.

200

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

Ejemplo

{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

setEmailTags

Establece los valores de las etiquetas para la dirección de correo electrónico.

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

Cabeceras de la solicitud

Nombre	Requerido	Valor	Descripción
Authorization	Sí	Token XXXX	Token de Dispositivo de la API para acceder a la API de Dispositivos. Reemplace XXXX con su token real de la API de Dispositivos.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
application	string	Código de aplicación de Pushwoosh
email	string	Dirección de correo electrónico.
tags	object	Objeto JSON de etiquetas para establecer, envíe ‘null’ para eliminar el valor.
userId	string	ID de Usuario asociado con la dirección de correo electrónico.

200

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

Ejemplo

{
  "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 otros tipos de dispositivos se devolverá 200 OK, aunque las etiquetas no se guardarán.

Precaución

Por favor, evite establecer más de 50 valores de etiquetas en una sola solicitud /setEmailTags.

registerEmailUser

Asocia un ID de Usuario externo con una dirección de correo electrónico especificada.

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

Nota

Tenga en cuenta que este método no registra una dirección de correo electrónico en su base de usuarios; debe usarse solo para asignar ID de usuario a direcciones de correo electrónico que ya han sido registradas mediante la solicitud /registerEmail.

Se puede usar en la llamada a la API /createEmailMessage (el parámetro ‘users’).

Cabeceras de la solicitud

Nombre	Requerido	Valor	Descripción
Authorization	Sí	Token XXXX	Token de Dispositivo de la API para acceder a la API de Dispositivos. Reemplace XXXX con su token real de la API de Dispositivos.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
application*	string	Código de aplicación de Pushwoosh
email*	string	Dirección de correo electrónico.
userId*	string	ID de Usuario para asociar con la dirección de correo electrónico.
tz_offset	integer	Desplazamiento de la zona horaria en 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."
}

Ejemplo

{
  "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 datos sobre rebotes suaves, rebotes duros y quejas de correo electrónico, incluyendo la fecha, la dirección de correo electrónico y el motivo de cada rebote, utilice el método BouncedEmails.