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.
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'.
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.
basicFunction 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.
| 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:
|
| 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:
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 |
| 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:
|
| Adjuntos | Array of arrays JSON array with the attachments if you want to include them in the message. For example:
|
| 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.
|
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 |
| Res required | integer <int32> Response of the requested function
|
| 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. |
{- "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": [
- null
], - "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"
}[- {
- "Res": "10",
- "Error": "Required parameter missing",
- "idEnvio": "1228853777",
- "Destinatarios": "2",
- "Enviados": "[{\"Email\": \"destinatario@eldominio.com\",\"idMensaje\": \"108366478\"}]",
- "NoEnviados": "[{\"Nombre\": \"Ana Gonzalez\",\"Email\": \"noexiste@dominiomal.com\"}]",
- "Duplicados": "0"
}
]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
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Status of the sent notification. The possible statuses are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SistOperativo required | integer Type of operating system detected at destination (in openings)
|
{- "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"
}