CERTIFIED EMAIL

Certified EMAIL Sending API (7.0)

Download OpenAPI specification:Download

URL: /contacto.php Terms of Service

INTRODUCTION

Integration API for sending Certified EMAIL messages from your applications through https requests.

AUTHENTICATION

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



To use Basic Authentication you must include a header in your 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 build the string APIUser:APIToken and encode it in base64 using any base64encode function.

IMPORTANT NOTES

Empty connections: Please note that a repeatedly failed connection will be treated by the system as spam and may end up temporarily blocking the connection.

It is advisable to avoid repeated connections with incorrect data, or fast 'empty' connections (without actually sending anything) using the same data just to obtain the number of credits or the same report.

To obtain reports optimally in real time, we recommend configuring the API in your panel to receive them in a script on your website.


Request response: 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.

We always recommend setting this parameter because, for backward compatibility with previous API versions, all functions respond by default (if this parameter is not set) the way they did in older versions. Those older API-version results omit some of the variables included in this API version, which we consider important to ease integration and account information.

The included examples always assume you have set this parameter. If you are working directly with API version >= 5, we will assume you have set the parameter in every request.


Recommended workflow: The recommended workflow, being both the simplest and the most professional, is as follows:
- PROCESS 1: Sending a Certified EMAIL: Described in the EnviarEMAILCertificado function of this document.
- PROCESS 2: Automatic reception of reports on your website (process described in the 'Reception of delivery reports' section).

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 Certified Email

/EnviarEMAILCERTIFICADO

Function for sending Certified Email messages from your applications. Definition of the required 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
Remitente
required
string
Example: Remitente=tucorreo@tudominio.com

Sender of the Certified Email. It must be a valid email and must have been previously validated in the user control panel.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com","Variable_1":"Variable to personalize subject and message per recipient"}]

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


                  [
                    {
                        "Nombre": "Pedro Aicart",
                         "Email": "pedro@dominio.com"
                     },
                     {
                         "Nombre": "Ana Aguado",
                         "Email": "ana@empresa.com"
                     }
                  ]

ADVANCED: If you want to protect the notification with OTP, ID document, Certificate, etc.. you must add the following options as variables to each recipient:
PROTECCIONACCESO: It can be:
EMAIL: The system will ask the recipient for the email to which the notification was sent (low protection)
DNI: The recipient will be asked for their ID document to access the notification (You must include the recipient's ID document in the ValorBloqueo variable) (medium protection)
OTP: for protection via OTP, you must indicate the recipient's mobile number in ValorBloqueo (high protection)
CERTIFICADO: The system will ask the recipient to access with their digital certificate or electronic ID document. You must include the recipient's ID document in the ValorBloqueo variable (very high protection)
VALORBLOQUEO: In this variable you must include the blocking value corresponding to the ProteccionAccceso variable.
For example:


                  [
                    {
                        "Nombre": "Pedro Aicart",
                        "Email": "pedro@dominio.com",
                        "ProteccionAcceso": "OTP"
                        "ValorBloqueo": "34601234567"
                     },
                     {
                         "Nombre": "Ana Aguado",
                         "Email": "ana@empresa.com"
                         "ProteccionAcceso": "DNI"
                         "ValorBloqueo": "00000000T"
                     }
                  ]
Asunto
required
string
Example: Asunto=Esto es una Notificacion para {{Nombre}} con motivo de {{Variable_1}}

The subject of the certified email / of the notification

Mensaje
required
string
Example: Mensaje=A la atención de {{Nombre}} con NIF {{DNI}}, Te enviamos esta notificación .....

Message that will be sent to the recipient(s)

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

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

Aceptacion
string
Enum: "SI" "NO"
Example: Aceptacion=NO

Parameter used to request explicit acceptance or rejection by the recipient prior to viewing the notification. Options 'SI' or 'NO' (NO by default)

Caducidadaceptacion
integer
Example: Caducidadaceptacion=10

(Mandatory if Acceptance is enabled) It is the time during which the recipient will be able to accept or reject the notification. After this time, if it has not been accepted or rejected, it will expire. Value from 1 to 30 days

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....",
                         "Certificar": "1"
                     },
                     {
                         "Nombre": "otrodocumento.docx",
                         "Contenido": "IyBleHBvcnRlZCBmcm9tIGJhY2ts.....",
                         "Certificar": "1"
                     }
                  ]
Referenciausuario
string
Example: Referenciausuario=Tu referencia

Parameter used as a reference for the user. If you choose to receive the report at a URL, you will receive this parameter in the result of the sending.

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

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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

Report
string
Example: Report=0

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

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.

Remitente
required
string
Destinatarios
required
Array of any
Asunto
required
string
Mensaje
required
string
Fecha
string
Aceptacion
string
Caducidadaceptacion
integer
Adjuntos
Array of any
Referenciausuario
string
Resp
string
Report
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 Attached file not allowed.
-5 Not enough credits.

Error
string

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

Destinatarios
Array of arrays

Recipient data in an array in which idMensaje is added for each recipient. The idMensaje is the identifier of the message or group of messages sent. It serves, for example, as an identification to obtain the report of the sent message (whether the phone has been unsubscribed, delivery times, etc.). It will be received in the requests if you enable real-time report reception in a script on your website/server.

Cred
double

Credits remaining in the user account after sending.

Enviados
integer

Number of messages actually sent.

NoEnviados
integer

Number of erroneous/not sent recipients.

Duplicados
integer

Number of recipients not sent because they were duplicated.

CreditosUsados
integer

Number of Credits used.

Request samples

Content type
{
  • "Remitente": "tucorreo@tudominio.com",
  • "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\",\"Variable_1\":\"Variable to personalize subject and message per recipient\"}]",
  • "Asunto": "Esto es una Notificacion para {{Nombre}} con motivo de {{Variable_1}}",
  • "Mensaje": "A la atención de {{Nombre}} con NIF {{DNI}}, Te enviamos esta notificación .....",
  • "Fecha": "2022-05-01 15:10",
  • "Aceptacion": "NO",
  • "Caducidadaceptacion": "10",
  • "Adjuntos": [
    ],
  • "Referenciausuario": "Tu referencia",
  • "Resp": "JSON",
  • "Report": "0"
}

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 enabling 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 receiving 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 goal is to distinguish between the reports of the different services). The services referred to in this specification may receive

EMAILCERTIFICADO If the service refers to a report of a Certified EMAIL

Resultado
required
integer

Status of the notification sent. The possible statuses are:

STATUS DESCRIPTION MEANING
`10` Open Registered An open of the sent email has occurred.
`11` Delivered to the recipient The EMAIL has been delivered. If it is a Certified Email, you have a certificate in PDF format with Time stamping. 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, accessed and downloaded 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 open by the recipient.
`16` Delivered, opened and accepted Meaning: (Certified only) Acceptance of the notification was requested and the recipient has opened and accepted it.
`17` Delivered, opened and rejected Meaning: (Certified only) Acceptance of the notification was requested and the recipient has opened and rejected it.
`18` Delivered and opened. Expired Meaning: (Certified only) Acceptance of the notification was requested and the message has expired without being accepted.
`19` Delivered and expired Meaning: (Certified only) Acceptance of the notification was requested and the message has expired without being accepted.
`28` Temporary error at destination Meaning: There is a temporary error at destination (for example, a full mailbox).
`29` Message Cancelled Meaning: The message was cancelled by the user before being sent.
`50` The message cannot be delivered Meaning: An error has occurred at destination. For example, that the recipient does not exist.
`51` Non-existent 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` Expired Notification Meaning: The EMAIL could not be delivered, the notification has 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` Retrying. Meaning: The EMAIL has been attempted to be delivered to the destination server and there was 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 message is being sent.
`1003` Retrying Meaning: There was a problem at destination, the system is retrying.
Remitente
required
string

Sender used in the sending.

Destinatario
required
string

Email of the recipient the report refers to.

Fecha
required
string

Date of the report (date on which the carrier serving the destination mobile reports the new status)

Asunto
required
string

Subject of the sent message

idMensaje
required
integer

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

Referencia
required
string

User reference that was sent during the sending request.

CSV
string

Secure Verification Code received only if you already have generated certificates

Request samples

Content type
{
  • "Servicio": "EMAILCERTIFICADO",
  • "Resultado": "11",
  • "Remitente": "tucorreo@tudominio.com",
  • "Destinatario": "destino@dominio.com",
  • "Fecha": "2020-12-03 11:14:24",
  • "Asunto": "Asunto del email",
  • "idMensaje": "10573758",
  • "Referencia": "Su referencia si la indicó",
  • "CSV": "ASYYFRE5492HN776TFD"
}

Cancel Certified Email

/CancelarEMAILCERTIFICADO

Function to cancel a Certified Email previously scheduled via the sending function.

Authorizations:
basicAuth
query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identifier returned by the sending function.

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

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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.

Idmensaje
required
integer
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


>0 Number of messages cancelled.
-1 Authentication error.
-2 Incorrect data (You can only cancel your own identifiers; if you try to cancel message identifiers of another user, it could be considered an attack and limit your connection's access).
-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 The message has already been sent.
-5 The message is already cancelled.

Cred
double

Credits remaining in the user account after sending.

Request samples

Content type
{
  • "Idmensaje": "1283876988",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Reschedule Certified Email

/ReprogramarEMAILCERTIFICADO

Function to reschedule an email previously scheduled via the sending function that was scheduled to be processed in the future..

Authorizations:
basicAuth
query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identifier returned by the sending function.

Fecha
required
string
Example: Fecha=2022-12-03 11:14:24

New sending date.

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

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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.

Idmensaje
required
integer
Fecha
required
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


>0 Number of messages rescheduled.
-1 Authentication error.
-2 Incorrect data (You can only modify scheduled messages with identifiers sent from your account; if you try to modify message identifiers of another user, it could be considered an attack and limit your connection's access).
-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 The message has already been sent.
-5 The message is cancelled.
-6 The new date is not correct.
-7 The new date has already passed.

Cred
double

Credits remaining in the user account after sending.

Request samples

Content type
{
  • "Idmensaje": "1283876988",
  • "Fecha": "2022-12-03 11:14:24",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Query and download Certified EMAIL

/GetCertificadoEMAILCERTIFICADO

Obtaining the PDF file with the certificate of the message sent to a mobile via the API. This function is usually executed in response to a report reception with a certificate status (for example, result 14 -delivered and certified- in Certified EMAIL and 17, 160 or 181 -contract signed/perfected and certified- in the case of EMAIL Contract). A report and PDF are downloaded if the Phone is specified, or all recipients of the message if it is not specified.

Authorizations:
basicAuth
query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identifier returned by the sending function.

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

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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.

Idmensaje
required
integer
Resp
string

Responses

Response Schema:
string

Request samples

Content type
{
  • "Idmensaje": "1283876988",
  • "Resp": "JSON"
}

Response samples

Content type
In case of success, a zip file is downloaded. Contents of the ZIP:
-  Certificates in PDF format
-  CSV file with the result of the certified message to each recipient.

Simple Query of Certified EMAIL Report

/GetReportEMAILCERTIFICADO

Function to obtain the report of a sent certified email. It is recommended to enable report reception on your website instead of using this function. Looping requests (continuous querying of the status of the same message(s) in a loop) are considered an attack and may block your connection.

Authorizations:
basicAuth
query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identifier returned by the sending function.

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

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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.

Idmensaje
required
integer
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


1 Successful operation.
-1 Authentication error.
-2 You do not have permission to query this message.
-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 Error in response.

Programado
string

Date on which the message was or will be sent.

Remitente
string

Sender of the certified email.

Destinatario
string

Recipient of the certified email.

Cred
double

Credits remaining in the user account after sending.

Estado
integer

Current status of the message.

txtEstado
string

Text description of the message status.

Request samples

Content type
{
  • "Idmensaje": "1283876988",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Credit Query

/GetCreditos

Function that returns the number of credits in the account. It is a very occasional-use function since most functions return the number of Credits remaining in the user in their responses. Therefore, it is usually used simply as a test of operation or to obtain the number of credits occasionally

Authorizations:
basicAuth
query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Type of response to return as the result of the call.
ANT - (Deprecated). Kept for backward 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.

Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


1 The function completed successfully.
-1 Authentication error.

Cred
required
double

Credits remaining in the user account after sending.

Request samples

Content type
{
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]