HTTP API

1.Introduction

What is HTTP API?

El API HTTP es una herramienta que te permite integrar EnvialoSimple.com con tus aplicaciones mediante simples llamadas a URLs.

La interfaz (API) te ofrece innumerables funcionalidades agrupadas por módulos para facilitar su utilización e implementación.

A través de la nueva API HTTP de EnvialoSimple.com podrás enviar tu campañas de email marketing; crear, modificar y eliminar contactos, listas de contactos y campañas; consultar estadísticas y reportes integrando todas las funcionalidades de EnvialoSimple.com en tu propia aplicación.

All URLs have the same structure:

https://app.envialosimple.com/<modulo>/<accion>?APIKey=<api key>&format=<format>

<modulo>It represents a group of actions. It may take the values:

• campaign
• member
• report
• mailist

<accion> - Specific action to be carried out. This action depends on the module. It takes values such as "list", "add", "edit", etc.

<api key> - Authentication token. These tokens can be generated from your EnvialoSimple.com account in the "Advanced configuration".

<format> - Exit format of the request. Supported formats are:

• json
• xml

Reply (Structure)

Todas las respuestas empiezan con un nodo "root" seguido por "ajaxResponse" si es que el formato de salida es "json" o directamente los datos después del nodo "root" si el formato de salida es XML.

Si NO se producen errores durante la ejecución de la operación se retorna un nodo "success" junto a los datos correspondientes al método. De lo contrario encontraremos un nodo "errors" con códigos de error.

Example

{
            "root": {
                "ajaxResponse": {
                    "success": true,
                    <Specific reply of the service>
                }
            }
        }

{
            "root":{
                "ajaxResponse":{
                    "errors":{
                        <Error tokens>:<Error detail if applicable>
                    }
                }
            }
        }

{
        "root":{
            "ajaxResponse":{
                "errors":{
                "errorMsg_formValidations":{
                    "count":[
                    "notDigits"
                        ],
                    "absolutepage": [ ],
                    "filter": [ ],
                    "orderBy": [ ],
                    "desc": [ ],
                    "MailListsIDs": [ ]
                    }
                }
            }
        }
    }

1.List campaigns

Service:

/campaign/list

It lists all campaigns filtered by name.

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

ScheduleErrorStatus:

** Only relevant errors are documented.

2.Retrieve Campaign information

Service:

/campaign/load

It retrieves campaign information

Parameters:

Errors:

Exit structure

3.Create or Modify campaign information

Service:

/campaign/save

It creates or modifies campaign information. The call must be made via POST

Parameters:

** Only relevant fields are documented.

Errors:

Exit structure:

** It returns all input parameters and adds the following data:.

4.Campaign preview by e-mail or browser

Service:

/campaign/preview

Campaign preview by e-mail or browser. This service supports a special type of exit format ("format") . The type "email"

Parameters:

** Only relevant fields are documented.

Errors:

Exit structure:

5.Delete campaign

Service:

/campaign/delete

It deletes a campaign permanently

Parameters:

Errors:

If you are not able to delete the campaign, in the reply we will have a node "errors" with the IDs of the campaigns that were not deleted and another node "countNotDeleted" with the number of campaigns that were not deleted
Ej: errors:{notDeleted:["10","2"]},countNotDeleted: "2.

Ej: errors:{notDeleted:["10","2"]},countNotDeleted: "2"

Exit structure

6.Create body of the campaign (HTML/Plain text)

Service:

/content/edit

It creates/modifies the body of the campaign e-mail

7.Send a campaign

Service:

/campaign/resume

Once the campaign has been created with its content, you can start sending e-mails to recipients. This method also needs to be used when restarting a paused campaign

Parameters:

Errors:

Exit structure

8.Pause campaign

Service:

/campaign/pause

It stops the sending of a campaign. This campaign can later be resumed with a call to the service "/campaign/resume"

Parameters:

Errors:

Exit structure

9.Useful implementation examples in PHP

In this example, we will :

• 1. Create a campaign with the following characteristics:
• 1. Name: 'Summer deal'
• 2. Subject: 'Amazing Summer Deals!!!'
• 3. Contact list ID: 1
• 4. Sender e-mail ID: 21
• 5. Reply e-mail ID: 21
• 6. Follow links: yes
• 7. Count open messages: yes
• 8. Use Google Analytics: yes
• 9. Send report after process has been completed: yes
• 10. Add public file: yes
• 2. Change status of sending to ACTIVE: yes
• 3. Schedule to send now: yes
• 4. Create e-mail content and assign it to the campaign.
• 5. Send the campaign.

Script

textarea with the script code member.php

Script PHP Exit

New Campaign: XX

Body of the created campaign

Campaign was sent. To check progress and results of the campaign, go to the "reports" module.

<?php$baseURL = 'https://app.envialosimple.com';$apiKey = 'TU LLAVE';// Creo nueva campaña$params = array();$params['APIKey']=$apiKey;$params['CampaignName']='Promo Verano';$params['CampaignSubject']='Super Ofertas de verano!!!';$params['MailListsIds']=array('1','2');$params['FromID']='21';$params['ReplyToID']='21';$params['TrackLinkClicks']='1';$params['TrackReads']='1';$params['TrackAnalitics']='1';$params['SendStateReport']='';$params['AddToPublicArchive']='1';$params['ScheduleCampaign']='1';$params['SendNow']='1';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/campaign/save/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "Error al crear la campaña\n";print_r($response);exit;}$id = $response['root']['ajaxResponse']['campaign']['CampaignID'];$name = $response['root']['ajaxResponse']['campaign']['Name'];echo "Nueva Campaña: $id $name\n";if($response['root']['ajaxResponse']['campaign']['integrity']['status']=='1'){if($response['root']['ajaxResponse']['campaign']['integrity']['subject']=='-1'){echo "Debes asignar un Asunto.\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['schedule']=='-1'){echo "Debes determinar una configuracion de envio\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['content']=='-1'){echo "Debes determinar un contenido de la campaña\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['replyTo']=='-1'){echo "Debes determinar un remitente 'reply to'\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['fromTo']=='-1'){echo "Debes determinar un origen 'from'\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['maillist']=='-1'){echo "Debes determinar una o varias listas de contactos\n";}}// Crea contenido$params = array();$params['APIKey']=$apiKey;$params['CampaignID']=$id;$params['HTML']='<h1>Super ofertas de verano!!!</h1><p>Mirá nuestros <a href="http://mitiendita.com.ar">productos</a></p> <br/> para desuscribirse click <a href="%UnSubscribe%">aquí</a>';$params['PlainText']="Super ofertas de verano!!!\n\n\tMira nustros productos en http://mitiendita.com.ar";// Asigno contenido a la campaña.$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/content/edit/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "No se pudo asigar el contenido del email a la campaña\n";print_r($response);exit;}echo "Cuerpo de campaña creado\n";// Envio la campaña$params = array();$params['APIKey']=$apiKey;$params['CampaignID']=$id;$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/campaign/resume/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "Error al enviar la campaña\n";print_r($response);exit;}if($ok){echo "Campaña enviada. Para ver el avance y el resultado de la campaña ver el modulo de 'reportes'\n";}?>

1.Create body of the campaign (HTML/Plain text)

Service:

/content/edit

It retrieves, creates or modifies the campaign e-mail body. If the service is called via GET, it retrieves record information indicated by the CampaignID parameter. If it is via POST, it creates or updates record data indicated by the CampaignID parameter.

Parameters:

Note:

In the e-mail content, you will find a link to unsubscribe from contact list.

It can be provided in 2 ways:

a) If the content has been provided via URL (remote content), you must indicate in the RemoteUnsubscribeBlock parameter the link to unsubscribe.

b) If the content has been provided via HTML parameter, the parameter needs to have the unsubscribe link together with the e-mail content. Link to unsubscribe: ‹span›To unsubscribe from our list do the following‹/span› ‹a href="%UnSubscribe%" target="_blank"›Click here‹/a›

The link to unsubscribe is mandatory, if it is not present, the API will return the error "errorMsg_unSubscribeTagMissing"

Errors:

Exit structure

** Only relevant fields are documented.

2.List templates

Service:

/template/gallery

Recupera el listado de plantilla

Parameters:

Note: Each one of the filters per category generates a search of type (OR); the combination of both filters generates a search of type (OR) AND (OR)Ej. SELECT ... WHERE ( 'filterListByCategory'=5 OR 'filterListByCategory'=7 ) AND ('filterListByCategory2'=16)

Errors:

Exit structure

** Only relevant fields are documented.

3.List template categories

Service:

/campaign/templatecategories

It retrieves category list used to group templates

list.category[]List of general categories.

list.color[]List of categories per color.

Exit structure:

1.List contacts

Service:

/member/list

List all contacts from all list filtering by e-mail

Parameters:

Errors:

Exit structure:

** Only relevant fields are explained or listed

2.Create or modify contact information

Service:

/member/edit

It retrieves, creates or modifies contact information.

This service behaves in different ways depending on how we make the call. If we do it via GET and pass the MemberID parameter, it will try to retrieve the contact information. If we use POST, it will try to modify or create the contact depending on whether the MemberID parameter is defined or not.

Parameters:

Errors:

Exit structure:

** Only relevant fields are explained and listed.

3.Change contact status (Subscribe, unsubscribe, Disassociate, etc)

Service:

/member/changestaus

It modifies the status of one or more contacts associated to one or more lists.

Parameters:

Errors:

Exit structure:

changestatus: {
            detail: {
            changed: {
                2:["4","9"],
                1:["4","9"]
                     }
                    }
                SubscriptionStatus: "Subscribed"
                  }
            countChanged: 2

4.Unsubscribe contacts per e-mail

Service:

/member/unsubscribebyemail

It removes one or more contacts from one or several lists filtering by e-mail

Parameters:

Errors:

Exit structure:

5.Useful implementation examples in PHP:

In this example, we will :

Create contact with e-mail=juanperez@gmail.com, Name=Juan, last name=Perez and SUBSCRIBE to list with ID=1 .

Subscribe contact to list with ID=2.

Unsubscribe from list 1 the contact created in step 1

Look for contact created in step 1 within list 2

Script

TEAXTAREA with the code of the script member.php

Script PHP Exit

Nuevo Contacto: 19962 - juanperez@gmail.com: Juan Perez

User successfully subscribed to list 2

User successfully unsubscribed from list 1

El usuario 19962 - juanperez@gmail.com (Juan Perez) esta suscripto a la lista 2

<?php$baseURL = 'https://app.envialosimple.com';$apiKey = 'KEY';//Create a new contact in the list 1$params = array();$params['APIKey']=$apiKey;$params['MailListID']=1;$params['Email']='juanperez@gmail.com';$params['CustomField1']='Juan';$params['CustomField2']='Perez';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/edit/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$id = $response['root']['ajaxResponse']['member']['MemberID'];$email = $response['root']['ajaxResponse']['member']['Email'];$nombre = $response['root']['ajaxResponse']['member']['CustomFields']['item']['CustomField1']['Values']['Option'][0]['Value'];$apellido = $response['root']['ajaxResponse']['member']['CustomFields']['item']['CustomField2']['Values']['Option'][0]['Value'];echo "Nuevo Contacto: $id - $email: $nombre $apellido \n";//Subscribe contact to list with ID=2$params = array();$params['APIKey']=$apiKey;$params['MailListsIds']=array(2);$params['MemberIds']=array($id);$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/changestatus/SubscriptionStatus/Subscribed/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$exito = $response['root']['ajaxResponse']['success'];$count = $response['root']['ajaxResponse']['countSubscribed'];if($exito && $count=1){echo "Contacto suscripto correctamente a la lista 2\n";}else{echo "No se pudo suscribir correctamente a la lista 2\n";print_r($response);exit;}//Unsubscribe contact from list 1$params = array();$params['APIKey']=$apiKey;$params['MailListsIds']=array(1);$params['MemberIds']=array($id);$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/changestatus/SubscriptionStatus/Unsubscribed/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$exito = $response['root']['ajaxResponse']['success'];$count = $response['root']['ajaxResponse']['countUnsubscribed'];if($exito && $count=1){echo "User successfully unsubscribed from list 1\n";}else{echo "No se pudo desuscribir correctamente de la lista 1\n";print_r($response);exit;}//Look for contact created in step 1 within list 2$params = array();$params['APIKey']=$apiKey;$params['MailListID']=2;$params['filter']='juanperez';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/listbymaillist/format/json?'.http_build_query($params));curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);foreach ($response['root']['ajaxResponse']['list']['item'] as $item){$tmpid = $item['MemberID'];$tmpemail = $item['Email'];$tmpnombre = $item['CustomFields']['item']['CustomField1']['Values']['Option'][0]['Value'];$tmpapellido = $item['CustomFields']['item']['CustomField2']['Values']['Option'][0]['Value'];echo "El Contacto $tmpid - $tmpemail ($tmpnombre $tmpapellido) esta suscripto a la lista 2\n";}?>

1.Display contact lists

Service:

/maillist/list

It displays all contact lists

Parameters:

Errors:

Exit structure:

2.Create or modify contact list

Service:

/maillist/edit

It retrieves, creates and edits the attributes of a contact list. If the service is called via GET, it retrieves the information of the requested list. If it is via POST, it creates or updates (if the parameter MaillistID is entered) the name of the contact list.

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

1.Real-time monitoring

Service:

/report/livetrack

It checks the progress of campaign e-mails sent.

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

2.General report

Service:

/report/livetrack

It informs details of a campaign and all e-mails possibly sent. (When sending multiple e-mails of a campaign, they are kept by compatibility with a previous system).

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

3.Reports distributed through out the time

Service:

/report/trackintime

It reports e-mails read (unique and total) and clicks distributed through out the time. It is recommended to use Flot (http://code.google.com/p/flot/ to view this report

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

4.Summarized report

Service:

/report/trackgraph

Summarized report with e-mails read, bounced, of-subscriptions, delivered, etc. Flot is recommended to view this report (http://code.google.com/p/flot/)

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

5.Export reports of e-mails read and clicks

Service:

/report/exportreads | /report/exportlinks

It generates a CSV file with the information of e-mails read (/report/exportreads) and clicks (/report/exportlinks) of a campaign. Once the CSV file is generated, the service "/download/export?FileToken=" has to be called to download it.

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

If you are interested in getting more reports or making suggestions on new reports, please get in touch with us!. https://administracion.donweb.com/clientes/index.php?modulo=soporte&archivo=asistente

1.Real-time monitoring

Service:

/administratoremail/list

List e-mail addresses

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

2.Create or modify e-mail address information

Service:

/administratoremail/edit

It retrieves, creates or edits the attributes of an e-mail address. If the service is called via GET, it retrieves the information of the requested record. If the service is called via POST, it creates or updates (Id the parameter EmailID is entered) the record data.

Parameters:

Errors:

Exit structure:

** Only relevant fields are documented.

3.Automatic generation of DKIM Keys

Service:

/administratoremail/genKey

Generates automatically a couple of keys to use in the DKIM configuration

Parameters:

Exit structure:

** Only relevant fields are documented.

4.Check DKIM configuration

Service:

/administratoremail/testdkim

Check whether the DKIM signature configuration and the DNS information are correct and updated.

Parameters:

** Only relevant fields are documented.

5.Delete e-mail address

Service:

/administratoremail/delete

It deletes logically an e-mail address, the record will no be displayed in the lists but the system will still be able to use it to guarantee that other campaigns using the address work fine.

Parameters:

1.Status of the administrator account

Service:

/administrator/status

This service provides information related to the administrator account status such as: available credits, programmed tasks, import/export/purge processes of members from contact lists

Parameters:

Exit structure:

Each one of the elements of the array has the following data:

1.Listar campos personalizados

Service:

/customfield/list

List custom fields that have been configured

Parameters:

Errors:

Exit structure:

2.Create or Modify the information of a custom field

Service:

/customfield/edit

It retrieves, creates or modifies the attributes of a custom field. If the service is called via GET, it retrieves the information of the requested record. If the service is called via POST, it creates or updates (if the CustomFieldID is entered) record data.

Parameters:

Note: Parameters ItemsNames and ItemsValues are related since both keys have corresponding keys. Eg. ItemsNames[5 has the label of the option whose value is indicated in ItemsValues[5]

Errors:

Exit structure:

** Only relevant fields are documented.

3.Delete custom field

Service:

/customfield/delete

It deletes a custom field permanently, the record will not be available to be used.

Parameters:

Errors:

Exit structure: