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 email.

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 email. Consulte la tabla de Parámetros de Notificaciones a continuación.

Parámetros de notificaciones

Nombre	Tipo	Requerido	Descripción
send_date	string	Sí	Define cuándo enviar el email. 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 u object	No	Línea de asunto del email. El email siempre estará en el idioma del contenido. Si subject no contiene un idioma coincidente para content, el asunto estará vacío.
content	string u object	No	El contenido del cuerpo del email. Puede ser una cadena para contenido HTML simple o un objeto para versiones localizadas.
attachments	array	No	Los archivos adjuntos del email. 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 email con una campaña específica.
ignore_user_timezone	boolean	No	Si es true, envía el email inmediatamente, ignorando las zonas horarias del usuario.
timezone	string	No	Envía el email según la zona horaria del usuario. Ejemplo: "America/New_York".
filter	string	No	Envía el email a los usuarios que coinciden con una condición de filtro específica.
devices	array	No	Lista de direcciones de email (máximo 1000) para enviar emails 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 emails del parámetro devices.
users	array	No	Si se establece, el mensaje de email solo se entregará a los User ID 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 los tags de dispositivo.
conditions	array	No	Condiciones de segmentación usando tags. Ejemplo: [["Country", "EQ", "BR"]].
from	object	No	Especifique un nombre y un email de remitente personalizados, anulando el predeterminado en las propiedades de la aplicación.
reply-to	object	No	Especifique un email de respuesta personalizado, anulando el predeterminado en las propiedades de la aplicación.
bcc	array	No	BCC (Copia de carbón oculta): array de direcciones de email que reciben una copia del email sin que otros destinatarios las vean.
email_type	string	No	Especifique el tipo de email: "marketing" o "transactional". Si se omite, los usuarios con PW_ControlGroup: true no recibirán el mensaje.
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 único de mensaje 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áx. 30) para aplicar el frequency capping por dispositivo. Nota: Asegúrese de que el Frequency capping global esté configurado en el Panel de Control.
capping_count	integer	No	El número máximo de emails 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 email no se contará para el capping de futuros emails.
capping_avoid	boolean	No	Si se establece en true, el capping no se aplicará a este email específico.
send_rate	integer	No	Limite 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 email específico.

Ejemplo de solicitud

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // requerido. Token de acceso a la API desde el Panel de Control de Pushwoosh
    "application": "APPLICATION_CODE",  // requerido. Código de aplicación de Pushwoosh.
    "notifications": [{
      "send_date": "now",               // requerido. YYYY-MM-DD HH:mm  O 'now'
      "preset": "ERXXX-32XXX",          // requerido. Copie el código de preset de Email de la barra de URL de
                                        //           la página del editor de Contenido de Email en el Panel de Control de Pushwoosh.
      "subject": {                      // opcional. Línea de asunto del mensaje de email.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // opcional. Contenido del cuerpo del email.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // opcional. Archivos adjuntos del email
        "name": "image.png",            //           "name" - nombre del archivo
        "content": "iVBANA...AFTkuQmwC" //           "content" - contenido del archivo codificado en base64
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // opcional. Permite establecer una URL personalizada para la cabecera "Link-Unsubscribe"
      "campaign": "CAMPAIGN_CODE",      // opcional. Para asignar este mensaje de email a una campaña particular,
                                        //           agregue un código de campaña aquí.
      "ignore_user_timezone": true,     // opcional.
      "timezone": "America/New_York",   // opcional. Especifique para enviar el mensaje de acuerdo con
                                        //           la zona horaria establecida en el dispositivo del usuario.
      "filter": "FILTER_NAME",          // opcional. Envíe el mensaje a usuarios específicos que cumplan con las condiciones del filtro.
      "devices": [                      // opcional. Especifique las direcciones de email para enviar mensajes de email dirigidos.
        "email_address1",               //           No más de 1000 direcciones en un array.
        "email_address2"                //           Si se establece, el mensaje solo se enviará a las direcciones de
      ],                                //           la lista. Se ignora si se utiliza el Grupo de Aplicaciones.
      "use_auto_registration": true,    // opcional. Registra automáticamente los emails especificados en el parámetro "devices"
      "users": [                        // opcional. Si se establece, el mensaje de email solo se entregará a los
        "userId1",                      //           ID de usuario especificados (registrados a través de la llamada /registerEmail).
        "userId2"                       //           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": { // opcional. Marcadores de posición para contenido dinámico en lugar de los valores de los tags de dispositivo.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // opcional. Condiciones de segmentación, vea la nota a continuación.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // opcional. Especifique un nombre de remitente y una dirección de email de remitente
        "name": "alias from",           //           para reemplazar el "Nombre del remitente" y el "Email del remitente" predeterminados
        "email": "from-email@email.com" //           configurados en las propiedades de la aplicación.
      },
      "reply-to": {                     // opcional. Especifique una dirección de email para reemplazar la
        "name": "alias reply to ",      //           "Dirección de respuesta" predeterminada configurada en las propiedades de la aplicación.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // opcional. BCC: array de direcciones de email que reciben una copia sin que otros destinatarios las vean.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // opcional. "marketing" o "transactional".
                                        // Si se omite, los usuarios con PW_ControlGroup: true no recibirán el mensaje.
      "email_category": "category name",// requerido cuando email_type es "marketing". Nombre de la categoría.
      "transactionId": "unique UUID",   // opcional. Identificador único de mensaje para evitar el reenvío
                                        //           en caso de problemas de red. Almacenado en el lado
                                        //           de Pushwoosh durante 5 minutos.
      // Parámetros de Frequency capping. Asegúrese de que el Frequency capping global esté configurado en el Panel de Control.
      // El Frequency capping no se aplica a los mensajes transaccionales.
      // En todos los demás casos, incluido el "email_type" omitido, se aplica el frequency capping.
      "capping_days": 30,               // opcional. Cantidad de días para el frequency capping (máx. 30 días)
      "capping_count": 10,              // opcional. El número máximo de emails 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": true,          // opcional. Si se establece en true, este email no
                                        //           se contará para el capping de futuros emails.
      "capping_avoid": true,            // opcional. Si se establece en true, el capping no se aplicará a
                                        //           este email específico.
      "send_rate": 100,                 // opcional. Límite de throttling.
                                        //           Limite 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": true,          // opcional. Si se establece en true, el límite de throttling no se aplicará a
                                        //           este email específico.
    }]
  }
}

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 tags

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

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

Descripción del operando

• EQ: el valor del tag es igual al operando;
• IN: el valor del tag se cruza con el operando (el operando siempre debe ser un array);
• NOTEQ: el valor del tag no es igual a un operando;
• NOTIN: el valor del tag no se cruza con el operando (el operando siempre debe ser un array);
• GTE: el valor del tag es mayor o igual que el operando;
• LTE: el valor del tag es menor o igual que el operando;
• BETWEEN: el valor del tag 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).

Tags de tipo 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"];

Tags de tipo 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].

Tags de tipo 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

Tags de tipo Boolean

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

Tags de tipo 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

Tags de País e Idioma

El valor del tag de Idioma es un código de dos letras en minúsculas según ISO-639-1
El valor del tag 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 email 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 email.
language	string	Configuración regional 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	User ID para asociar con la dirección de email.
tz_offset	integer	Desplazamiento de la zona horaria en segundos.
tags	object	Valores de tag 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",   // requerido. Código de aplicación de Pushwoosh.
    "email":"email@domain.com",          // requerido. Dirección de email a registrar.
    "language": "en",                    // opcional. Configuración regional de idioma.
    "userId": "userId",                  // opcional. User ID para asociar con la dirección de email.
    "tz_offset": 3600,                   // opcional. Desplazamiento de la zona horaria en segundos.
    "tags": {                            // opcional. Valores de tag para establecer para el dispositivo registrado.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // establece la lista de valores para Tags de tipo Lista
       "DateTag": "2024-10-02 22:11",    // tenga en cuenta que la hora debe estar en UTC
       "BooleanTag": true                // los valores válidos son: true, false
    }
  }
}

Códigos de respuesta

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

status_code	Significado	¿Reintentar?
200	Éxito — la dirección de email está registrada.	No — listo.
210	Error de argumento/validación — la solicitud fue entendida pero rechazada (dirección en lista negra, email invá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 inválido o un campo requerido faltante.	No — corrija la solicitud, no la repita.
403	Prohibido — token de la API de Dispositivos invá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 supera 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 @ es inválida.
hwid (email) has invalid domain part	La parte del dominio es inválida.
hwid (email) has disposable domain	La dirección utiliza un dominio de email 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 email.

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 email 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 email utilizada en la solicitud /registerEmail.

200

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

Ejemplo

{
  "request": {
    "application": "APPLICATION_CODE",  // requerido. Código de aplicación de Pushwoosh
    "email": "email@domain.com"         // requerido. Email a eliminar de los suscriptores de la aplicación.
  }
}

setEmailTags

Establece los valores de los tags para la dirección de email.

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 email.
tags	object	Objeto JSON de tags para establecer, envíe ‘null’ para eliminar el valor.
userId	string	User ID asociado con la dirección de email.

200

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

Ejemplo

{
  "request": {
    "email": "email@domain.com",                  // requerido. Dirección de email para la que se establecerán los tags.
    "application": "APPLICATION_CODE",            // requerido. Código de aplicación de Pushwoosh.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // hora en UTC
      "BooleanTag": true                          // los valores válidos son: true, false
    },
    "userId": "userId"                            // opcional. User ID asociado con la dirección de email.
  }
}

Nota

Para otros tipos de dispositivos se devolverá 200 OK, aunque los tags no se guardarán.

Precaución

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

registerEmailUser

Asocia un User ID externo con una dirección de email especificada.

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

Nota

Tenga en cuenta que este método no registra una dirección de email en su base de usuarios; debe usarse solo para asignar ID de usuario a direcciones de email 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 email.
userId*	string	User ID para asociar con la dirección de email.
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", // requerido. Código de aplicación de Pushwoosh.
    "email": "email@domain.com",       // requerido. Dirección de email del usuario.
    "userId": "userId",                // requerido. User ID para asociar con la dirección de email.
    "tz_offset": 3600                  // opcional. Desplazamiento de la zona horaria en segundos.
  }
}

Nota

Para recuperar datos sobre rebotes suaves (soft bounces), rebotes duros (hard bounces) y quejas de email, incluyendo la fecha, la dirección de email y la razón de cada rebote, utilice el método BouncedEmails.