[ES] – enviarMail: Envio de Mail y Suscripciones

Formato de Pedido
<enviarEmail>
   <suscripto>
      <email>EMAIL DEL SUSCRIPTO</email>
      [
      <nombre>NOMBRE DEL SUSCRIPTO</nombre>
      ]
      [
      <apellido>APELLIDO DEL SUSCRIPTO</apellido>
      ]
   </suscripto>
   <campanaId>ID DE LA CAMPAÑA</campanaId>
   <email>
      [
      <viaUrl>DIRECCION DE LA PIEZA</viaUrl>
      ]
      [
      <piezaEnUtf8>0 ó 1</piezaEnUtf8>
      ]
      [
      <piezaFija>DIRECCION DE PIEZA FIJA</piezaFija>
      ]
      [
      <asunto>ASUNTO DE E-MAIL</asunto>
      ]
      [
      <tags>
         <tag1>REEMPLAZO 1</tag1>
         ....
         <tagN>REEMPLAZO       N</tagN>
      </tags>
      ]
   </email>
   <serverKey>SERVER KEY</serverKey>
</enviarEmail>
Explicación de los campos
  • El campo email es mandatorio. Si email=0 o false, entonces no se enviará ningún e-mail y solo se ingresará el suscripto al sistema.
  • El id de campaña se obtiene desde la plataforma del DMDS: En la vista de detalle de una Campaña de tipo API podrá encontrarse el campo Campaña ID para copiar.
  • Si email.viaUrl está presente, se espera que sea la URL de una pieza HTML. Si no está presente se usará la pieza asociada a la Campaña de tipo API (ver Cómo Crear una Campaña tipo API)
  • email.piezaEnUtf8 sólo debe enviarse si se envía utilizando email.viaUrl y define la codificación de la pieza (UTF-8 o IS0-8859-1)
  • Los tags pueden reemplazarse por una enumeración, que determinará el numero de repeticiones aplicadas con la marca <%REPEAT TAG%>. Por ejemplo:
<tag1>Reemplazo1</tag1>
<tag2>
<item>Reemplazo 2.1</item> <item>Reemplazo 2.2</item> <item>Reemplazo 2.3</item>
</tag2>

determinará 3 loops sobre una marca <%REPEAT tag1 %>. Si se utiliza del modo usual (individual) se utilizará el 1º reemplazo disponible.

  • Asimismo se pueden utilizar Tags Estructurados, con atributos. En este caso, por ejemplo “Reemplazo1” podría ser en cambio una estructura de un nivel más:
<tag1>
<attr1>Valor para tag1.attr1</attr1> <attr2>Valor para tag1.attr2</attr2> <attr3>Valor para tag1.attr3</attr3>
</tag1>

Siendo reemplazadas las apariciones del string tag1.attr1 por “Valor para tag1.attr1” y así sucesivamente.
Esta última funcionalidad se puede combinar con las enumeraciones, haciendo posible la construcción de piezas complejas sumamente personalizadas.

Funcionamiento
  • Se agregará el suscripto a la base de datos, si es que no estaba.
  • Se relacionará al suscripto con el origen asociado a la campaña
  • Si el campo email es 0 no se realiza ninguna acción más
  • Si hay un valor en el campo email, se enviará un e-mail. Los datos de este e-mail son, por defecto, los del envío asociado a la campaña y algunos pueden configurarse en el pedido al API (viaUrl, piezaFija y asunto).
Uso de los Tags Simples

Por convención los tags reemplazables son de la forma: XYZtagXYZ, para evitar reemplazos erróneos.

Hay dos modos de uso disponibles: Individual y modo Repeat.

Uso individual

Es el utilizado normalmente en DMDS: XYZNOMBREXYZ se reemplaza por el nombre del suscripto. Nótese que el reemplazo es insensible a mayúsculas (XYZNOMBREXYZ equivale a xyznombrexyz y a XyZnOMbReXyZ).

De este modo, si en email.tags encontramos <XYZTAG1XYZ>REEMPLAZO 1</ XYZTAG1XYZ > entonces cada ocurrencia de la palabra XYZTAG1XYZ en la pieza será reemplazada por REEMPLAZO 1. Introduciremos el uso del Repeat con un ejemplo.

Suponga una pieza con este texto:

La mejor opción para usted es XYZURLXYZ

<%REPEAT XYZURLXYZ%>

Vea esta sección: XYZURLXYZ donde encontrará su XYZBUSQUEDAXYZ

<%/REPEAT XYZURLXYZ%>

<%REPEAT XYZSEGUNDABUSQUEDAXYZ%>

No hay novedades sobre su XYZSEGUNDABUSQUEDAXYZ

<%/REPEAT XYZSEGUNDABUSQUEDAXYZ%>

Y un pedido a enviarMail con los siguientes tags:

<XYZBUSQUEDAXYZ>Perro</XYZBUSQUEDAXYZ>
<XYZSEGUNDABUSQUEDAXYZ>Gato</ XYZSEGUNDABUSQUEDAXYZ > 
<XYZURLXYZ>
<item>golderetriever.com</item>
<item>google.com</item>
<item>pedigree.com</item>
</XYZURLXYZ>
Pieza Resultante

1| La mejor opción para usted es golderetriever.com

2| Vea esta sección: golderetriever.com donde encontrará su Perro

3| Vea esta sección: google.com donde encontrará su Perro

4| Vea esta sección: pedigree.com donde encontrará su Perro

5|

6| No hay novedades sobre su Gato

Notemos que:
  1. Cuando se utiliza un tag enumerado sin estar dentro de un contexto de <%REPEAT %>, se utiliza el primer reemplazo disponible:

    1| La     mejor opción para usted es golderetriever.com
  2. El cuerpo de un <%REPEAT %> se repite una vez por cada reemplazo para un tag enumerado. El contexto solo se abre para un tag solo y los REPEAT no pueden anidarse:

    2| Vea esta sección: golderetriever.com donde encontrará su Perro

    3| Vea esta sección: google.com donde encontrará su Perro

    4| Vea esta sección: pedigree.com donde encontrará su Perro

    Si XYZBUSQUEDAXYZ fuese un enumerado, de todos modos solo aparecería el primer ítem (Perro)

  3. Para un REPEAT, un tag individual es considerado como un enumerado de un solo ítem6| No hay novedades sobre su Gato
  4. Véase que el comienzo de la marca de cierre es <%/ (Menor-Porciento-Barra) y no </% (Menor-Barra-Porciento) como sería un cierre de tag típico de HTML
Uso de los Tags Estructurados

Nuevamente, pueden utilizarse en modo Individual y en modo Repeat.

El uso de estos tags es: NombreTag(punto)NombreAtributo

Ejemplo de uso individual: Si en email.tags aparece:

<XYZTAG1XYZ>
<XYZATTR1XYZ>Atributo 1</XYZATTR1XYZ>
<XYZATTR2XYZ>Atributo 2</XYZATTR2XYZ>
</XYZTAG1XYZ>

cada ocurrencia del string XYZTAG1XYZ.XYZATTR1XYZ en la pieza sera reemplazada por Atributo 1 y XYZTAG1XYZ.XYZATTR1XYZ será reemplazada por Atributo 2.

Nñtese que XYZTAG1XYZ sola no será reemplazada.

Ejemplo de uso de Tags Estructurados en modo Repeat:

Pieza

¡Tenemos novedades sobre el INTERES.NOMBRE!

<%REPEAT INTERES%>

<h1>INTERES.NOMBRE</h1>

Visite la dirección INTERES.LINK

O bien contactese con INTERES.CONTACTO

<%/REPEAT INTERES%>

<%REPEAT SEGUNDABUSQUEDA%>

No hay novedades sobre su SEGUNDABUSQUEDA.NOMBRE

La búsqueda vence el día SEGUNDABUSQUEDA.VENCIMIENTO

<%/REPEAT SEGUNDABUSQUEDA%>

Y un pedido a enviarMail con los siguientes tags:

<INTERES>
   <item>
      <NOMBRE>Torneo de Futbol</NOMBRE>
      <LINK>
      http://www.torneofutbol.com/</LINK>
      <CONTACTO>webmaster@torneofutbol.com</CONTACTO>
   </item>
   <item>
      <NOMBRE>Torneo de Basquet</NOMBRE>
      <LINK>
      http://www.torneobasquet.com/</LINK>
      <CONTACTO>webmaster@torneobasquet.com</CONTACTO>
   </item>
</INTERES>
<SEGUNDABUSQUEDA>
   <NOMBRE>Viaje a la costa</NOMBRE>
   <VENCIMIENTO> 08/12/2010</VENCIMIENTO>
</SEGUNDABUSQUEDA>
Pieza Resultante

1| ¡Tenemos novedades sobre el Torneo de Futbol!

2| <h1>Torneo de Futbol</h1>

3| Visite la dirección http://www.torneofutbol.com/

4| O bien contactese con webmaster@torneofutbol.com

5| <h1> Torneo de Basquet</h1>

6| Visite la dirección http://www.torneobasquet.com/</

7| O bien contáctese con webmaster@torneobasquet.com

8|

9| No hay novedades sobre su Viaje a la costa

10| La búsqueda vence el día 08/12/2010

Notemos que:

La funcionalidad es una fusión natural del modo Repeat y los Tags Estructurados, valen exactamente las mismas aclaraciones que para el Modo Repeat de los tags simples, en particular:

  • Cuando se utiliza un tag enumerado sin estar dentro de un contexto de <%REPEAT %>, se utiliza el primer reemplazo disponible
  • El cuerpo de un <%REPEAT %> se repite una vez por cada reemplazo para un tag enumerado. El contexto sólo se abre para un tag solo, y los REPEAT no pueden anidarse. Para un REPEAT, un tag individual es considerado como un enumerado de 1 solo item.

Como puede verse en el ejemplo, ni los tags ni los atributos deben necesariamente comenzar y terminar con XYZ. De todos modos es fuertemente recomendable seguir esta convención, ya que todas las apariciones serán reemplazadas. Si se utilizan palabras de uso cotidiano como “link” y “contacto” es muy probable que el e-mail se corrompa.

Formato de Respuesta
<enviarMailResponse>
<return> XXX - Mensaje Human Readable </return>
</enviarMailResponse>

XXX - Mensaje Human Readable

Esto es: 3 números, espacio, guión, espacio, Mensaje Legible.

Lista de Respuestas de Error Esperadas
  • 100 – No se encontró serverKey
  • 101 – serverKey incorrecta
  • 102 – Pedido Incorrecto
  • 107 – campanaId incorrecto
  • 120 – No hay envío asociado a campanaId
  • 120 – No hay envío efectivo asociado a la campanaId
  • 121 – Ocurrió un problema al insertar el suscripto
  • 122 – Relays no configurados para la cuenta. Contacte a su administrador.
  • 124 – No hay respuesta del servidor SMTP
  • 125 – Problema al enviar el e-mail: Descripción
  • 110 – Algún campos mandatario no esta configurado
  • 111 – El e-mail ingresado es incorrecto
  • 112 – La direccion url para buscar la pieza es incorrecta
  • 113 – Url o pieza en Url incorrectas
  • 114 – Pieza de e-mail mal formateada
  • 115 – Pieza con paths relativos sin path absoluto inferible
  • 116 – Problemas al reemplazar Tags en pieza: Descripción
Lista de Respuestas de Éxito Esperadas
  • 200 – Nuevo suscripto insertado
  • 201 – Suscripto existente. Nueva relación
  • 202 – Suscripto existente, relación existente
  • 300 – E-mail enviado. Nuevo suscripto insertado
  • 301 – E-mail enviado. Suscripto existente. Nueva relación
  • 302 – E-mail enviado. Suscripto existente, relación existente
  • 303 – E-mail enviado.

Ver También: