Campañas

Listar tus campañas

Para ver todas las campañas que tienes en tu cuenta, puedes hacer un GET a /campaigns.

$campaigns = file_get_contents(
    "https://api.myperfit.com/v2/micuenta/campaigns",
    false,
    stream_context_create(['http'=> [
        'method' => 'GET',
        'header' => "X-Auth-Token: $access_token"
        ]])
);

La respuesta que recibirás será algo como esto:

{
    "href": "/micuenta/campaigns",
    "success": true,
    "paging": {
        "offset": 0,
        "limit": 20,
        "results": 2,
        "total": 2
    },
    "data": [
        {
          "id": 1,
          "name": "Mi Primer Campaña",
          "description": "Este es un comentario acerca de la campaña",
          "tags": ["newsletter", "otro tag"],
          "type": "SIMPLE",
          "state": "DRAFT",
          "recipients": null,
          "launchMode": "NOW",
          "launchDate": null,
          "created": "2015-11-20T10:00:00Z",
          "lastModified": "2015-11-20T10:00:00Z",
          "archived": null,
          "thumbnail": "https://thmb.myperfit.com/.../thumb1.png",
          "metrics": null
        },
        {
          "id": 2,
          "name": "Otra Campaña",
          "description": "Este es un comentario acerca de otra campaña",
          "tags": ["oferta"],
          "type": "SIMPLE",
          "state": "SENT",
          "recipients": 1234,
          "launchMode": "SCHEDULED",
          "launchDate": "2015-11-21T12:30:00Z",
          "created": "2015-11-20T10:00:00Z",
          "lastModified": "2015-11-20T10:00:00Z",
          "archived": null,
          "thumbnail": "https://thmb.myperfit.com/.../thumb2.png",
          "metrics": {
            "sent": 1234,
            "sentP": 100,
            "opened": 200,
            "openedP": 16,
            "clicked": 50,
            "clickedP": 4,
            "bounced": 30,
            "bouncedP": 2.4
          }
        }
    ]
}

EL listado de campañas muestra información reducida de cada campaña, para ver más detalles debes hacer GET a la campaña específica utilizando su id, por ejemplo: GET https://api.myperfit.com/v2/micuenta/campaigns/1

Opciones de filtrado y ordenamiento

Como todos los listados, también puedes indicar en la url las opciones de paginación (limit, offset), ordenamiento (sortby, sortdir), filtrado (filter) y realizar una búsqueda por nombre (q).

$campaigns = file_get_contents(
    "https://api.myperfit.com/v2/micuenta/campaigns?limit=10&offset=5&sortby=created&filter[state]=DRAFT&q=*keyword*",
    false,
    stream_context_create(['http'=> [
        'method' => 'GET',
        'header' => "X-Auth-Token: $access_token"
        ])
    ]])
);

Las opciones válidas para sortby son:

  • name (default)
  • state
  • stateGroup
  • created
  • launchDate

Las opciones válidas para filter son:

  • filter[state]: filtrado por estado de campaña, puede ser: DRAFT, SCHEDULED, PENDING_APPROVAL, SENDING, SENT, CANCELLED
  • filter[tags]: filtrado por etiquetas
  • filter[archived]: si es true se listan sólo las campañas archivadas, si es false (valor por defecto) sólo se muestran las no archivadas.

Crear y Enviar una nueva campaña

Para poder crear una campaña se deben seguir los siguientes pasos:

  1. Creación de la campaña, seteo de propiedades y destinatarios
  2. Creación del contenido dentro de la campaña, seteo de asunto y remitente
  3. Seteo del contenido HTML
  4. Envío inmediato o programado

1. Creación de la campaña

Para crear una nueva campaña el único campo requerido es su nombre. Pero para hacer las cosas en forma más fácil indicaremos todas sus propiedades en el mismo POST. Queremos enviarle esta campaña a todos los contactos de las listas 1 y 2, pero vamos a excluir a los contactos de la lista 3.

$result = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/campaigns',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n" .
                    "X-Auth-Token: $access_token",
        'content' => http_build_query([
            'name' => 'Nueva Campaña',
            'description' => 'Esta es la descripción de la nueva campaña',
            'tags' => ['prueba'],
            'include' => [ lists => [1,2] ],
            'exclude' => [ lists => [3] ]
        ])
    ]])
);

$campaign_id = json_decode($result)->data->id;

El API nos responderá con la nueva campaña creada:

{
    "href": "/micuenta/campaigns",
    "success": true,
    "data": {
       "id":3,
       "name":"Nueva Campaña",
       "description":"Esta es la descripción de la nueva campaña",
       "tags":[
          "prueba"
       ],
       "type":"SIMPLE",
       "state":"DRAFT",
       "launchMode":"NOW",
       "launchDate":null,
       "archived":null,
       "created":"2016-10-21T16:43:49Z",
       "lastModified":"2016-10-21T16:43:49Z",
       "recipients":null,
       "thumbnail":null,
       "metrics":null,
       "options":{
          "SHARE_FACEBOOK":"1",
          "GA_CAMPAIGN_NAME":"Nueva Campaña",
          "GOOGLE_ANALYTICS":"1",
          "SHARE_LINKEDIN":"1",
          "TRACK_LINKS":"1",
          "VIEW_ONLINE":"1",
          "SHARE_TWITTER":"1",
          "SHARE_FORWARD":"1"
       },
       "include":{
          "lists":[1,2],
          "interests":[],
          "campaigns":[]
       },
       "exclude":{
         "lists":[3],
         "interests":[],
         "campaigns":[]
       },
       "contents":[]
    }
}

Nos interesa conservar el id de la nueva campaña para usarlo en los próximos pasos.

Como se ve en la respuesta, hay más opciones que podemos configurar:

  • options

    • TRACK_LINKS: Habilitar el monitoreo de clicks.
    • GOOGLE_ANALYTICS: Habilitar la integración con Google Analytics (parámetros utm en los links).
    • GA_CAMPAIGN_NAME: Nombre de campaña en Google Analytics, por defecto será el nombre de la campaña en Perfit.
    • VIEW_ONLINE: Habilitar el link en el encabezado a la versión online del contenido.
    • SHARE_FACEBOOK: Habilitar el link en el encabezado para compartir en Facebook.
    • SHARE_TWITTER: Habilitar el link en el encabezado para compartir en Twitter.
    • SHARE_LINKEDIN: Habilitar el link en el encabezado para compartir en LinkedIn.
    • SHARE_FORWARD: Habilitar el link en el encabezado para reenviar.
  • include

    • lists: Listas a incluir en esta campaña.
    • interests: Intereses a incluir en esta campaña.
    • campaigns: Resultados de otras campañas a incluir en esta campaña.
  • exclude

    • lists: Listas a excluir en esta campaña.
    • interests: Intereses a excluir en esta campaña.
    • campaigns: Resultados de otras campañas a excluir en esta campaña.
  • contents: Array con los contenidos de la campaña, por ahora sólo está soportado tener un único contenido por campaña. Los contenidos deben crearse por separado, como se muestra en la próxima sección.

Mientras una campaña esté en estado DRAFT, podremos modificar todos sus elementos usando el método PUT.

2. Creación del contenido dentro de la campaña

Para crear el contenido, debemos indicar:

  • type: Para uso a través de la API se debe indicar siempre HTML.
  • subject: El asunto del correo a enviar.
  • from: La dirección de email del remitentre.
  • fromName: El nombre del remitente.

Opcionalmente, se pueden indicar también:

  • replyTo: La dirección de email donde recibir las respuestas.
  • replyToName: El nombre de quien recibirá las respuestas.
  • unsubscribeText: El texto de desuscripción ubicado al pie del contenido.

$result = file_get_contents(
    "https://api.myperfit.com/v2/micuenta/campaigns/$campaign_id/contents",
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n" .
                    "X-Auth-Token: $access_token",
        'content' => http_build_query([
          'type' => 'HTML',
          'subject' => 'Mirá todas las cosas nuevas que tenemos para vos',
          'from' => 'novedades@miempresa.com',
          'fromName' => 'Novedades',
        ])
    ]])
);

$content_id = json_decode($result)->data->id;

La respuesta con el nuevo conteido creado será:


{
    "href": "/micuenta/campaigns/3/contents",
    "success": true,
    "data": {
       "id":5,
       "type":"HTML",
       "subject":"Mirá todas las cosas nuevas que tenemos para vos",
       "from":"novedades@miempresa.com",
       "fromName":"Novedades",
       "replyTo":"",
       "replyToName":"",
       "unsubscribeText":"Haz click en el siguiente link para dejar de recibir estos mensajes:",
       "thumbnail":"https://thmb.myperfit.com/.../thumb.png"
    }
}

3. Seteo del contenido HTML

Ahora ya podemos insertar el cuerpo del contenido en formato HTML.


$result = file_get_contents(
    "https://api.myperfit.com/v2/micuenta/campaigns/$campaign_id/contents/$content_id.html",
    false,
    stream_context_create(['http'=> [
      'method'=>'PUT',
      'header' => "Content-Type: text/html\r\n" .
                  "X-Auth-Token: $access_token",
      'content' => '<h1>Aquí va el contenido</h1>'
    ]])
);

4. Envío inmediato o programado

Para enviar la campaña se debe hacer POST /campaigns/:id/launch.


$result = file_get_contents(
    "https://api.myperfit.com/v2/micuenta/campaigns/$campaign_id/launch",
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n" .
                    "X-Auth-Token: $access_token",
        'content' => http_build_query([
            'launchDate' => '2016-11-01T10:30:00Z'
        ])
    ]])
);

Si la campaña no pasa la validación, se recibirá un error como este:


{
   "href":"/v2/micuenta/campaigns/3/launch",
   "success":false,
   "error":{
      "status":400,
      "type":"INVALID_REQUEST",
      "userMessage":"Cannot launch campaign, validation failed.",
      "moreInfo":"https://developers.myperfit.com/errores#INVALID_REQUEST"
   }
}

Es recomendable hacer un GET /campaigns/:id/validate antes de intentar enviar la campaña para obtener un detalle de las validaciones de la campaña y saber si es necesario corregir algo.

Si todo esta bien, esta acción creará una tarea asincrónica que se ocupará de procesar los contactos según las opciones elegidas y encolar la campaña para su envío en la fecha indicada por launchDate. Si no se indica launchDate la campaña se envía lo antes posible.


{
   "href":"/v2/micuenta/campaigns/5/launch",
   "success":true,
   "task":{
      "id":329763688,
      "type":"CAMPAIGN_LAUNCH",
      "name":"Lanzamiento campaign Nueva Campaña 2",
      "state":"QUEUED",
      "cancellable":true,
      "message":"Pending execution",
      "owner":"diego",
      "created":"2016-10-21T17:59:53Z",
      "init":null,
      "end":null,
      "completed":0.0,
      "eta":-1,
      "request":"/v2/test1203/campaigns/229/launch",
      "parameters":{
         "campaignId":229,
         "launchDate":"2016-12-01T10:30:00Z"
      },
      "result":null
   }
}

Puede verificarse el avance y resultados de la tarea, como se muestra en la seccion Tareas.