Uploading Data and Sending Emails via FTP

Through an FTP account provided by Planisys with a user and password, port 12125, and SSL enabled, you can upload a CSV (Comma Separated Values) file.

Note

There is only one FTP account per DMDS

The CSV can be generated with

  • a text editor

  • an automatic output from a program or database

  • saving an Excel spreadsheet as a CSV file

The fields are separated by a single fixed separator, which is the semicolon.

If a field contains a semicolon within its value, it can be escaped with a backslash: \;.

The first line of the CSV is called the header and indicates what to do with the following lines.

All lines in the CSV must have the same number of fields separated by semicolons.

CSV processing is flexible and discards lines with a different number of fields than specified by the header, as well as discarding lines with emails that have incorrect syntax or nonexistent domains.

You can create two types of CSV

  • a passive CSV that is only used to update data

  • an active CSV that updates data and also sends an email for each line

Passive CSVs

The passive CSV is a CSV whose header indicates that it will only be used to update data.

The header fields can be the fixed ones (written exactly as follows): Default Fields

  • EMAIL (mandatory, the CSV cannot be processed without this field)

  • NOMBRE (Name)

  • APELLIDO (Last Name)

  • SEXO (only M or F is accepted)

  • INVALIDO (only 0 or 1 is accepted)

  • ORIGEN (Source)

  • FECHANAC (only YYYY-MM-DD is accepted)

  • TITULO (Title)

  • DOCUMENTO (Document)

  • CELULAR (Cellphone)

  • MAILALTERNATIVO (Alternative Email)

  • TWITTER

  • FACEBOOK

  • INSTAGRAM

and additional fields defined in the DMD can be added, or Custom Fields, such as

  • XYZTELCELXYZ

  • XYZDNIXYZ

  • XYZEMPLEADORXYZ

etc.

Warning

The XYZ fields must be defined beforehand in the DMDS to avoid typos and the proliferation of incorrect fields. If there are fields with incorrect syntax that do not match those listed above, the operation will be aborted with the message: >>>>>>>>>>>>>>>>>>>>>>>Header error - invalid field name … aborting”

The INVALIDO field is used to invalidate an email if it is 0, or to revalidate it if it is 1.

The ORIGEN is the name of a list to which an email is associated.

Note

An email can be associated with several listas (lists), also interchangeably called orígenes (sources)

The file with the .csv extension must be placed in the /private directory, which is visible upon accessing via FTP.

Periodically, the system takes these files and moves them to private/processed

Processing is complete when the file, for example named archivo1.csv, becomes archivos1.csv-YYYY-MM-DD-HH-MM-SS and a similar file archivos1.log-YYYY-MM-DD-HH-MM-SS is generated, which shows what happened with each line.

Line-by-Line LOG Messages of the Passive CSV

For each line, the CSV processor will print a status.

The following are examples of possible status lines

  • linenr=416 status={“status”:”existing ok”} email=jkgomez01@hotmail.com , means that the email was already in the database as valid

  • linenr=927 status={“status”:”existing invalidated”} email=jkgomez19999@hotmail.com , means that the email was already in the database as invalid

  • ……………….. Line 224 CORRECTED <jkgomez@gmial.com> to <jkgomez@gmail.com> , the lexicographical similarity processor detected a typo and automatically corrected the email address

  • ……………….. Line 171 ERROR incorrect email <jjkgomez@fdhsjafhjdddddd.com.ar> invalid [The domain name fdhsjafhjdddddd.com.ar does not exist.] non-existent domain

  • ……………….. Line {} ERROR Missing or extra values 7 != 8n^ , incorrect number of fields, different from what the header indicates

At the end of the log file, there is a line with the totals, e.g.

>>> 13287 lines processed, 20 lines with error, 172 emails corrected, 3 new emails, 141 existing invalidated emails

Active CSVs

If the __CAMP_NUMID__ field appears in the header, it is considered an ACTIVE CSV and will not only update data line by line but also send an email line by line. It must be an API campaign number obtained from the DMDS web page.

Warning

It is mandatory for an active CSV to also include the __HTML_URI__ field in the header. This field is used to specify the URL of the email piece to be sent in each line.

Optionally, the __SENDER_NAME__ field can be included in the header, which will be appended to the actual sender specified by the API campaign.

The subject is also predefined by the API campaign along with the sender. However, it can be overwritten using the __ASUNTO__ field as well as ASUNTO_URI which allows specifying a URL from which to retrieve the subject.

Line-by-Line LOG Messages of the Active CSV

In addition to the passive CSV messages, new messages may appear here.

  • SEND linenr=5 status={“status”:”ok”,”sent”:1,”eeid”:”9f977887-967e-4042-bc2b-c54444332218”} email=jkgomez01@gmail.com data={“campana_id”: 72, “email”: “true”, “contact”: {“email”: “jkgomez01@gmail.com”}, “html_url”: “https://www.planisys.net/newsletter/1623/EnvioFactura.html”, “sender_name”: “REMITENTE1”}

This is a debug message indicating the eeid interchangeably called envio efectivo ID or batch id which can then be queried via API or Web to see what events it has (besides sending, there may be read, click, and bounce events).

Note

In the same FTP account that Planisys provides to its DMDS clients, HTMLs, images, attachments, and other accessory files can be stored in the /web directory to be sent via email. Only static content can be hosted.

Active CSV Example

Here we show an example of an active CSV, where an email will be sent to soporte@planisys.com and another to soporte@avascloud.net.

Emojis and UTF-8 characters have been included in the subject. The API campaign number is extracted from the creation of the campaign.

EMAIL;__CAMP_NUMID__;__HTML_URI__;__SENDER_NAME__;XYZNOMBREXYZ;XYZAPELLIDOXYZ;__ASUNTO__
soporte@planisys.com;71206;https://imagenes.planisys.com/Planisys-Template.html;Novedades Planisys;Soporte;Técnico;😊🥳 Novedades Planisys áiéóúÑ
soporte@avascloud.net;71206;https://imagenes.planisys.com/Planisys-Template.html;Novedades Planisys;Soporte;Técnico;😊🥳 Novedades Avascloud áiéóúÑ

The piece that is seen when accessing via the Web contains variables of the XYZ type to be replaced, using the fields provided both in the CSV and in the same system where fields related to the destination email addresses are stored.

../_images/planisys-template-desktop.jpg

Last Updated on 2024-08-21