EMAIL Sending API (7.0)

Download OpenAPI specification:Download

INTRODUCTION

API for integrating the sending of EMAIL messages from applications via https requests.

AUTHENTICATION

In your user account you will find the API User and the API Token, both are necessary to make the API REST requests to the API functions. For security reasons, requests must be made via POST and using the Secure HTTPS protocol.



To use Basic Authentication you must include a header in the requests of the type: Authorization: Basic Base64StringAPI where Base64StringAPI is the Base64 encoding of the string APIUser:APIToken, you can find your API User and API Token in your user account under Your Data -> Configure Account.



To generate the Base64-encoded string, simply generate the string ApiUser:APIToken and encode it in base64 using any base64encode function.

IMPORTANT NOTES

Empty connections: It is important to bear in mind that a repeatedly erroneous connection will be treated by the system as spam and may lead to temporarily blocking the connection.

It is advisable to avoid making repeated connections with erroneous data or quick 'empty' connections (without sending) with the same data to obtain the number of credits or the same report.

To obtain reports optimally in real time, it is recommended to configure the API in the panel to receive them in a script on your website.


Response of the requests: Most functions have a parameter called 'Resp'. This parameter defines the format of the response that will be returned. It can be TXT, JSON, XML or undefined.

It is always recommended to define this parameter since all functions, for compatibility with previous versions of the API, respond by default (if this parameter is not defined) as they did in old versions. In these results from previous API versions, some of the variables included in this version of the API are omitted, which we consider important to facilitate integration and account information.

In the included examples it is always assumed that you have defined the parameter. If you are working directly with API version >= 5, we will assume that you have defined the parameter in all requests.


Validation of the sender Domain: Before being able to use this API, you must have validated with your assigned account manager the domain you are going to use as sender and added the SPF and DKIM records we indicate to your DNS.

This will allow the system to send correctly by encoding the email to maximize delivery to recipients. It is also advisable to consult with your account manager about the IP warming process for sending if you are going to perform mass sendings.


Recommended operation: The recommended operation, being the simplest and at the same time the most professional, is the following:
- PROCESS 1: Sending EMAIL : Described in the EnviarEMAIL function of this document.
- PROCESS 2: Automatic reception of reports on your website (process described in the section 'Reception of delivery reports'.

basicAuth

HTTP Basic authentication. Use your API User as the username and your API Token as the password (you will find them in your panel, under Your Data → Configure Account). The resulting header is Authorization: Basic base64(APIUser:APIToken). Most HTTP libraries build it automatically (curl -u, requests auth=, Ruby's basic_auth, etc.) without needing to encode the base64 by hand.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Send Email

/EnviarEMAIL

Function for sending Email messages from applications. Definition of the necessary parameters.

ATTENTION: Check the real-time report reception section if you want to receive the status of the emails and the recipient's interactions in real time in a script on your website.

Authorizations:
basicAuth
query Parameters
Nombreremitente
string
Example: Nombreremitente=My name

Name of the Email sender.

Emailremitente
required
string
Example: Emailremitente=minombre@micorreo.com

Sender of the Email. It must be a valid email and the domain must have been validated in your account, with the SPF and DKIM records added to your DNS and operation verified.

Replyto
string
Example: Replyto=minombre@micorreo.com

Email to which the recipient will reply.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com","Variables":[{"Nombre":"Motivo","Valor":"Felicitarte"},{"Nombre":"Razon","Valor":"Tu 25 cumpleaños"]}]

JSON array with the recipients of the email. You can add variables if you want to personalize Subject and Message per recipient. For example:


                  [
                    {
                        "Nombre": "Pedro Aicart",
                         "Email": "pedro@dominio.com",
                         "Referencia": "12345678T",
                         "Variables": [
                                 {
                                      "Nombre": "Accion",
                                       "Valor": "Transferencia"
                              },
                               {
                                      "Nombre": "Importe",
                                       "Valor": "10.000"
                              },
                       ]
                     },
                     {
                         "Nombre": "Ana Aguado",
                         "Email": "ana@empresa.com",
                         "Referencia": "36578294H",
                         "Variables": [
                                 {
                                      "Nombre": "Accion",
                                       "Valor": "Devolución"
                              },
                               {
                                      "Nombre": "Importe",
                                       "Valor": "127"
                              },
                        ]
                     }
                  ]
Asunto
required
string
Example: Asunto=This is a message for ###Nombre### on the occasion of ###motivo###

The subject of the email

Plantilla
integer
Example: Plantilla=1234567

The Id of the template you have created within the user panel. It is an optional parameter, you can send the HTML directly in Message or send this data to reference the template created in the panel. The variables within the template must be of the type ###Variabel### which will then be personalized per recipient. See the Message parameter to review the reserved variables.

Mensaje
string
Example: Mensaje=Html content that is going to be sent

Message that will be sent to the recipient(s), it is optional, you can send the message here or choose to use the Template parameter to send the corresponding template. The variables within the template must be of the type ###Variabel### which will then be personalized per recipient. There are reserved variables that can be used directly in the HTML and that will be updated with the corresponding values, these are:
###email### : It will be changed for the recipient's email ###destinatario###: Name of the recipient ###__fechahora__###: Date/Time of the sending (CET) ###__fecha__###: Date of the sending ###__hora__###: Time of the sending ###url_ver_en_web###: It will be modified for the link to the version viewed on web, example: 'if you do not see this email correctly click here'. Attention, the HideInWebView class is a class that allows, in our system, that once it appears in the web version, that content disappears. It is usually used so that, once it is in the web version, that message does not appear again, avoiding misunderstandings.
###url_unsubscribe###: It is the unsubscribe Url if you want us to manage it from the system, it will be added to your unsubscribe list.

SPECIAL FUNCTION: If you want an element (div, span, p,...) not to appear in the web view (when clicking view on web), you must add the hiddeninwebsite class to that element class="hiddeninwebsite"

Fecha
string
Example: Fecha=2022-05-01 15:10

Date on which the sending is scheduled, the message will be sent on that date. By default "" which means send immediately. Format Year-Month-day hour:minute. The time reference is CET/CEST (Time zone of Spain).

Intervaloprohibido
Array of arrays
Example: Intervaloprohibido=[{"HoraInicio":"22:00","HoraFin":"9:00","Accion":"1"}]

JSON array with the start and end hours of the forbidden sending interval. For example:


                    {
                        "HoraInicio": "22:00",
                         "HoraFin": "8:00"
                     },
Adjuntos
Array of arrays

JSON array with the attachments if you want to include them in the message. For example:


                  [
                    {
                        "Nombre": "documento.pdf",
                         "Contenido": "JVBERi0xLjcNJeLjz9MNCjg0IDAgb2JqDTw...."
                     },
                     {
                         "Nombre": "otrodocumento.docx",
                         "Contenido": "IyBleHBvcnRlZCBmcm9tIGJhY2ts....."
                     }
                  ]
Seguimientoaperturas
integer
Example: Seguimientoaperturas=1

If activated (1, by default) the openings of the sent emails will be tracked, if deactivated (0) no tracking will be done and you will not receive the opening reports in the report reception in your script.

Seguimientoclicks
integer
Example: Seguimientoclicks=1

If activated (1, by default) the clicks in the sent emails will be tracked, if deactivated (0) no tracking will be done and you will not receive the click reports in the report reception in your script.

Listunsubscribe
string
Example: Listunsubscribe=<mailto:listrequest@dominio.com?subject=unsubscribe>, <https://dominio.com/unsubscribe/identific1234567>

If you send through CSA certified IPs it is mandatory to use this option or listHelp. It is a header supported by the main email managers that allows recipients to unsubscribe with one click. If you want unsubscribes to be managed automatically, leave this parameter and ListHelp blank

Listhelp
string
Example: Listhelp=<https://www.dominio.com/landing/listhelp>, <mailto:list-info@cominio.com>

If you send through CSA certified IPs it is mandatory to use this option or listUnsubscribe. It is a header supported by the main email managers that allows indicating a landing where the recipient can find out the reason for receiving this email and, if they cannot unsubscribe (for example because they are OTP or transactional/operational messages, the reasons for receiving them.

Referenciausuario
string
Example: Referenciausuario=Your reference

Parameter used as a reference for the whole campaign for the user. If you select to receive the report at a URL, you will receive this parameter in the result of the send and also the reference of each of the recipients if you indicated it in the user array.

Report
integer
Example: Report=0

If you want to receive reports in a script on your website (by activating the API configuration in the user panel).

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Type of response to return as the result of the call.
ANT - (Obsolete). Kept for compatibility with previous versions
JSON - The response will be returned in JSON
XML - The response will be returned in XML
TXT - The response will be returned in Text format

Request Body schema:

Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.

Nombreremitente
string
Emailremitente
required
string
Replyto
string
Destinatarios
required
Array of any
Asunto
required
string
Plantilla
integer
Mensaje
string
Fecha
string
Intervaloprohibido
Array of any
Adjuntos
Array of any
Seguimientoaperturas
integer
Seguimientoclicks
integer
Listunsubscribe
string
Listhelp
string
Referenciausuario
string
Report
integer
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


>0 Number of messages sent.
-1 Authentication error.
-2 Not enough credits.
-3 Error in the call data. Required parameters are missing. In this case, you will get an additional parameter called Error with the description of the error.
-4 Attachment file not allowed.
-5 You do not have enough credits.

Error
string

In case of Res -3, you will get a descriptive error of the problem in this parameter.

idEnvio
integer

identifier of the campaign, it is equivalent to idCampaign received in the report and which is kept for compatibility with previous versions.

Destinatarios
integer

Number of recipients sent.

Enviados
Array of arrays

Data of the recipients in an array in which idMensaje is added for each recipient. The idMensaje is the Identifier of the message. It serves, for example, as identification to obtain the report of the sent message. It will be received in the requests if you activate the real-time report reception in a script on your website/server.

NoEnviados
Array of arrays

Erroneous/not sent recipients.

Duplicados
integer

Number of recipients not sent because they were duplicated.

Request samples

Content type
{
  • "Nombreremitente": "My name",
  • "Emailremitente": "minombre@micorreo.com",
  • "Replyto": "minombre@micorreo.com",
  • "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\",\"Variables\":[{\"Nombre\":\"Motivo\",\"Valor\":\"Felicitarte\"},{\"Nombre\":\"Razon\",\"Valor\":\"Tu 25 cumpleaños\"]}]",
  • "Asunto": "This is a message for ###Nombre### on the occasion of ###motivo###",
  • "Plantilla": "1234567",
  • "Mensaje": "Html content that is going to be sent",
  • "Fecha": "2022-05-01 15:10",
  • "Intervaloprohibido": "[{\"HoraInicio\":\"22:00\",\"HoraFin\":\"9:00\",\"Accion\":\"1\"}]",
  • "Adjuntos": [
    ],
  • "Seguimientoaperturas": "1",
  • "Seguimientoclicks": "1",
  • "Listunsubscribe": "<mailto:listrequest@dominio.com?subject=unsubscribe>, <https://dominio.com/unsubscribe/identific1234567>",
  • "Listhelp": "<https://www.dominio.com/landing/listhelp>, <mailto:list-info@cominio.com>",
  • "Referenciausuario": "Your reference",
  • "Report": "0",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Reception of delivery reports and status changes of sent messages

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

REAL-TIME RECEPTION OF DELIVERY STATUSES IN A SCRIPT ON YOUR SERVER.

By activating the option to receive reports in real time in a script on your server from your user panel, you will receive a POST request with the indicated format each time each sent message changes status.

You can configure to receive the requests with basic authentication and in JSON or FORM-DATA format

Authorizations:
basicAuth
Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Type of report you are receiving (the objective is to distinguish between the reports of the different services). The services to which this specification refers can receive EMAILTRANSACCIONAL If the service refers to a report of a Transactional EMAIL

Estado
required
integer

Status of the sent notification. The possible statuses are:

STATUS DESCRIPTION MEANING
`10` Opening Registered An opening of the sent email has occurred.
`11` Delivered to the recipient The EMAIL has been delivered. If it is a Certified Email, a certificate in PDF format with Time stamping is available. The system will continue recording the interactions.
`12` Reading/Access to the content Meaning:The recipient has accessed the reading of the content of the notification.
`13` Delivered, access and download Meaning: The recipient has received the notification by email, has opened it, the reading has been registered and, additionally, has downloaded the sent attachments.
`14` The recipient has replied Meaning: We have registered a reply from the recipient. If it is a Certified Email, you can certify the reply by requesting a certified addendum.
`15` The recipient has opened the message Meaning: We have registered an opening by the recipient.
`16` Delivered, opened and accepted Meaning: (Certified only) Acceptance of the notification has been requested and the recipient has opened and accepted it.
`17` Delivered, opened and rejected Meaning: (Certified only) Acceptance of the notification has been requested and the recipient has opened and rejected it.
`18` Delivered and opened. Expired Meaning: (Certified only) Acceptance of the notification has been requested and the message has expired without being accepted.
`19` Delivered and expired Meaning: (Certified only) Acceptance of the notification has been requested and the message has expired without being accepted.
`28` Temporary error at destination Meaning: There is a temporary error at destination (for example mailbox full).
`29` Message Cancelled Meaning: The message has been cancelled by the user before its sending.
`50` The message cannot be delivered Meaning: An error has occurred at destination. For example the recipient does not exist.
`51` Nonexistent Domain Meaning: An error has occurred at destination. The domain does not exist.
`52` Incorrect address format Meaning: An error has occurred at destination. The destination address is not correct.
`53` Notification Expired Meaning: The EMAIL could not be delivered, the notification is expired.
`54` Mailbox full Meaning: The EMAIL could not be delivered, destination mailbox full.
`55` The address does not exist Meaning: The destination server indicates that the mailbox does not exist.
`56` Message rejected Meaning: The recipient has marked the message as SPAM.
`57` Duplicate Meaning: Duplicate message in the campaign.
`58` User unsubscribed Meaning: The user has been unsubscribed from the destination server.
`59` Out of office Meaning: the mailbox is configured as out of office.
`60` Repeated error Meaning: After several delivery attempts, the destination mailbox still indicates a temporary error.
`101-120` Click Meaning: The recipient has opened the message and has clicked on link number 1-20 (number by order of appearance in the html) .
`999` Being retried. Meaning: The EMAIL has been attempted to be delivered to the destination server and there has been a problem, it is being retried.
`1000` The EMAIL has been sent. Meaning: The EMAIL has been sent, delivery to the destination server is being attempted.
`1001` EMAIL Scheduled Meaning: The message has been scheduled and will be delivered at the indicated time.
`1002` EMAIL in sending process Meaning: The sending of the message is being processed.
`1003` Retrying Meaning: There has been a problem at destination, the system is retrying.
Remitente
required
string

Sender used in the sending.

Destinatario
required
string

Email of the recipient to which the report refers.

RefCampaign
required
string

Generic reference of the campaign. It is the generic reference you indicated in the sending

RefMensaje
required
string

Specific reference of the recipient. It is the reference you indicated in the sending for this recipient

Fecha
required
string

Date of the report

idCampaign
required
integer

Unique identifier received as a response in the sending function (idEnvio received in the sending function)

idMensaje
required
integer

Unique identifier received as a response in the sending function (idMensaje received in the sending function)

Aperturas
required
integer

Number of openings registered in the message

IP
required
string

IP address from which the last opening is performed

Dispositivo
required
integer

Type of device with which the opening is performed

DEVICE DESCRIPTION
`0` No Opening
`1` Others
`2` Computer
`3` Phone
`4` Tablet
`5` Console
`6` TV
`7` Portable player
SistOperativo
required
integer

Type of operating system detected at destination (in openings)

OPERATING SYSTEM DESCRIPTION
`0` No Opening
`1` Others
`2` Android
`3` Windows
`4` Apple IOS
`5` Mac OSX
`6` Linux/Unix

Request samples

Content type
{
  • "Servicio": "EMAILTRANSACCIONAL",
  • "Estado": "11",
  • "Remitente": "tucorreo@tudominio.com",
  • "Destinatario": "destino@dominio.com",
  • "RefCampaign": "12333-4545-23233",
  • "RefMensaje": "12345678T",
  • "Fecha": "2020-12-03 11:14:24",
  • "idCampaign": "10573758",
  • "idMensaje": "33434444443",
  • "Aperturas": "1",
  • "IP": "10.10.20.200",
  • "Dispositivo": "2",
  • "SistOperativo": "3"
}