DMDS API REST v1 Examples with PHP

In this tutorial, we will show different examples of how to call the DMDS (Data-Mining and Delivery Services) REST API using PHP code.

Always keep in mind which method (GET, POST, DELETE, etc.) is used for each call, what headers are passed, and the structure of the JSON that needs to be formed. In this case, the data field might be empty for some calls, while for others, it needs to be filled with the necessary information for the call to be successfully executed.

The PHP file can be executed in two simple ways. The first way is to upload the file to your domain and call it via the URL. The second way is to work locally, where you need to configure the server so it can interpret PHP files. In this tutorial, the calls have been tested locally, and the response for each call is displayed in the browser.

Note

Remember that Authorization is unique to each person, as is the hostname.

Returns contact information

This call is made using the GET method, which allows us to obtain all the information of a contact by simply providing the person’s email. The resulting information includes the person’s name, surname, the campaigns they have participated in, the groups they belong to, etc.

<?php
    $ch = curl_init('https://api-dmds-host/v1/contacto/email@dominio');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Authorization: xxxxxxxx'));
    $result = curl_exec($ch);
    echo ($result);
?>

List invalid contacts

This part of the code will show us all the users who are invalid.

<?php

$ch = curl_init('https://api-dmds-host/v1/contactos/invalidos/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Authorization: xxxxxxxxx'));
$result = curl_exec($ch);
echo ($result);
?>

List global variables and their values

In the API, there are a series of global variables defined. To see what these variables are and their values, you can refer to the following code.

<?php
$ch = curl_init('https://api-dmds-host/v1/global/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: xxxxxxxxxxx'));
$result = curl_exec($ch);
echo ($result);
?>

The result displayed in the browser is as follows. You can also see in the image how we call the PHP file.

List campaigns

With the same structure as listing invalid contacts or global variables, we can list all existing campaigns. For this, the GET method is used.

<?php
    $ch = curl_init('https://api-dmds-HOST.planisys.net/v1/campania/');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Authorization: xxxxxxxxxxxxxxxx'));
    $result = curl_exec($ch);
    echo ($result);
 ?>

To list a particular campaign, you must provide the type and numid, for example.

<?php
    $data = array( "numid" => 12, "tipo"=>"api" );
    $data_string = json_encode($data);
    print( $data_string . "\n");
    $ch = curl_init('https://api-dmds-HOST.planisys.net/v1/campania/');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Authorization: xxxxxxxxxxxxxxxx', 'Content-Length: '.strlen($data_string)));
    $result = curl_exec($ch);
    echo ($result);
?>

Warning

The json_encode function, when it receives an empty array as a parameter, generates a list instead of a JSON with { and }, which is what is expected as a parameter.

Create or update a contact

With the following part of the code, you can create a new contact or update an existing one. The first variable defined is the email address, which acts as a primary key in the database. When updating a contact, we will always rely on their email since it is unique. You can also change their name, surname, etc., for all the fields you want to modify.

<?php
$data = array("email"=>"xxxxxx","nombre"=>"xxxx","apellido"=>"xx","sexo"=>"x","edad"=>"xxxxx","invalido"=>"0");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
            'Content-Type: application/json',
            'Authorization: xxxxxxxxxxx',
            'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Invalidate a contact

In the same update of a contact, you can invalidate or validate a contact. By default, the invalid variable is always set to zero. But in the case where a user wants to unsubscribe or invalidate their contact, setting this variable to one (invalid: 1) allows us to mark this contact as invalid.

<?php
$data = array("email"=>"xxxxxx","nombre"=>"xxxxx","apellido"=>"xxxxx","sexo"=>"x","edad"=>"xx","invalido"=>"1");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
              'Content-Type: application/json',
              'Authorization: xxxxxxxx',
              'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send an email

To send an email, we will differentiate between the types we want to send. First, there are two different calls for sending an email to a single recipient and another for sending to multiple recipients. For this, the change is very basic: replacing contact with contacts. Two other calls differentiate between sending HTML inline or via URI.

Generic call

<?php

$data = array("campana_id"=>1234, "email"=>true, "contacto"=>array("email"=>"xxxxxx","nombre"=>"xxxxxx","apellido"=>"xxxxxx"));
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/enviar/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Authorization: xxxxxxxxxxxx',
    'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send an email to a single recipient with HTML URI

To perform this send, you need to define certain fields, such as the email field, which must always be set to true to allow the email to be sent. If this value is false, messages cannot be sent. Other values to define are the campaign ID and the recipient’s email. Other values such as name, surname, and subject are optional. If you want to send HTML via URI, it is added in the html_url field. Remember to set your authorization value in the headers section.

<?php
$data = array("campana_id"=>123,"email"=>true, "contacto"=>array("email"=>"xxxxxxxxxm","nombre"=>"xxxxxxxx","apellido"=>"xxxxxx"), "html_url"=>"xxxxxxxxxxxx")
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_one_uri/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
     'Content-Type: application/json',
     'Authorization: xxxxxxxxxxx',
     'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send an email to a single recipient with HTML inline

The difference from the previous call is in how you define the HTML within the code. There are two ways to send an email with HTML inline. One is to define the HTML code within the script:

<?php
$data = array("campana_id"=>"xxxxxxxx","email"=>true, "contacto"=>array("email"=>"xxxxx","nombre"=>"xxxxx","apellido"=>"xxxxx"), "html"=>"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_one_inline/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
      'Content-Type: application/json',
      'Authorization: xxxxxxxx',
      'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send an email to more than one recipient with HTML URI

For this call, we will follow the same concept as the others when sending a message. In this case, we want to send to many recipients, so we will define an array of users we want to send to and change contact to contacts. In the example shown below, we send an email to two people, but you can define up to 50 recipients.

<?php
$data = array("campana_id"=>123,"email"=>true, "contactos"=>array(["email"=>"email1","nombre"=>"xxxxx","apellido"=>"xxxxxx"],["email"=>"email2","nombre"=>"xxxxxx","apellido"=>"xxxxxx"]), "html_url"=>"xxxxxxxxx");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_many_uri/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
      'Content-Type: application/json',
      'Authorization: xxxxxxxxx',
      'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send an email to more than one recipient with HTML inline

<?php
$data = array("campana_id"=>"xxxxxxxxxxx","email"=>true, "contactos"=>array(["email"=>"email1","nombre"=>"xxxxxxxxxx","apellido"=>"xxxxxxx"],["email"=>"email2","nombre"=>"xxxxxxx","apellido"=>"xxxxxxxxx"]), "html"=>"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_many_inline/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Authorization: xxxxxxxxxxxx',
        'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Create global variables

We can always create global variables. For the creation, we will use the POST method, where we pass a variable indicating the name of the global variable.

<?php
$data = array('nombre'=>'loreipsum2', 'valor'=>"43244654");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/global/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Authorization: xxxxxxx',
        'Content-Length: '.strlen($data_string))
 );
 $result = curl_exec($ch);
 echo ($result);
?>

Create a group

As we have seen earlier, when we create or modify a user, we can assign them to a group. To assign a group, you need to check if it exists. If it doesn’t, we can create it as follows.

<?php
$data = array('nombre'=>'loreipsum');
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/grupo/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Authorization: xxxxxxxxx',
        'Content-Length: '.strlen($data_string))
 );
 $result = curl_exec($ch);
 echo ($result);
?>

List filters

In the API system, different filters can be created to help specify the sends. To see this list of existing filters, follow the code mentioned below.

<?php
$ch = curl_init('https://api-dmds-host/v1/filtros/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Authorization: xxxxxxxxxx'));
$result = curl_exec($ch);
echo ($result);
?>

Add a phone number to a contact

With the following call, we can associate a phone number with a contact by specifying their email.

<?php
$data = array("email"=>"lxxxxx", "tlf"=>"+xx xxxxxxxxxxxx");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/telefono/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Authorization: xxxxxxxx',
        'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>

Send SMS

With the following call, we can send messages to a phone number by specifying the number and the message to be sent.

<?php
 $data = array("tlf"=>"+xx xxxxxxx", "msg"=>"Buenas tardes");
 $data_string = json_encode($data);
 $ch = curl_init('https://api-dmds-host/v1/envio/sms/');
 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
 curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_HTTPHEADER, array(
         'Content-Type: application/json',
         'Authorization: xxxxxxxxxx',
       'Content-Length: '.strlen($data_string))

  );
  $result = curl_exec($ch);
  echo ($result);
?>

Send a WhatsApp message with a phone number. First, you need to register your phone number with Twilio, which is a very easy and quick process. The process involves adding the number +14155238886 to your contacts and then opening a chat with this number in WhatsApp and typing join charcoal-shark. If we have done this step correctly, Twilio’s response will be as follows: For the call, we need to specify the number registered with Twilio, the previous step, and the message you want to send.

Última actualización el 2024-08-21