7. Web Service Rest tipo POST
Para la integración de nuestros clientes a la plataforma de Email de Aldeamo contamos con un API que permite a nuestros aliados envío y recepción de mensajes de correo electrónico. Esta tecnología facilita una integración rápida y transparente con el fin de potencializar el negocio de nuestros clientes y asociados.
A continuación, se detalla esta tecnología para un mayor entendimiento de su uso y complejidad.
Este api está basado en llamados HTTP POST hechos por el cliente a una URL.
Autenticación
: El cliente se autentica por medio de una llave API_KEY que se obtiene desde la plataforma y se envía de la siguiente manera.
{
"Authorization": "Bearer {API_KEY}",
}
Bajo este esquema se debe enviar una petición con la siguiente estructura.
URL para consumir el servicio:
https://api.ckpnd.com:5000/v1/email
http://api.ckpnd.com:5001
Ejemplo de la petición con Body HTML
Conten-Type: application/json
JSON petición:
{
"to": [
{
"email": "recipient@exampledomain.com"
}
],
"options": {
"cc": [
{
"email": "cc@exampledomain.com"
}
],
"bcc": [
{
"email": "bcc@exampledomain.com"
}
]
},
"from": {
"email": "sender@yourdomain.com",
"name": "John Doe"
},
"replyTo": {
"email": "sender@yourdomain.com",
"name": "John Doe"
},
"subject": "Hello World",
"body": "<h1>Hello World</h1>",
"attachments": [
{
"path":"https://i1.wp.com/cms.babbel.news/wpcontent/uploads/2015/05/HEAD02_FRA-20150703094705.gif"
},
{
"filename":"pdf1.pdf"
"path":"data:application/pdf;base64,iVBORw0KGgoAAAANSUhEUgA
AB9AAAAHWCAYAAAAvsRJeAAAABmJLR0QA/wD/AP+gvaeTAAAgAElEQVR4
nOzdaZBd530e¿+WPSXrWLL65dHc1tIPqCdI4YeQHw3t7b7vce8CuII19AJ9IW
7ntht9r+FRMTwQmmnuV+JwPnQHeiRwJxEIkCOgD0tDc9QmTPBrD/BVYqMp
hw/067670rn75OF8MUGHP0x1Dd7c33GqJ5AHZKZ1GjspNBF6Q6muYvXepH
7r2hSDhXxFTxkKC0cz97rC3c1cENADx/6sREvQudL1XmJpVsvByAw8fMRA8DD
49Je6d1L1+rdqPl7qHNP78SJrMwAx1IrDkXRvdMj/H8FtJ7nySqRB+lWfXXfe5c
755xzzjnnnHPOOeecc84555xzzjnnnHPOOeecc84555xzzjnnnHPOOecOgP8A
MOTZaSAigy0AAAAASUVORK5CYII="
}
]
}
Ejemplo de la petición usando Plantilla
{
"to": [
{
"email": "recipient@exampledomain.com"
}
],
"options": {
"cc": [
{
"email": "cc@exampledomain.com"
}
],
"bcc": [
{
"email": "bcc@exampledomain.com"
}
]
},
"from": {
"email": "sender@yourdomain.com",
"name": "John Doe"
},
"replyTo": {
"email": "sender@yourdomain.com",
"name": "John Doe"
},
"subject": "Hello World",
"template_id": "42eqy7oaigql",
"variables":{
"variable1":"random variable 1",
"variable2":"random variable 2"
}
"attachments": [
{
"filename":"image1.gif"
"path":"https://i1.wp.com/cms.babbel.news/wpcontent/uploads/2015/05/HEAD02_FRA-20150703094705.gif"
},
{
"filename":"pdf1.pdf"
"path":"data:application/pdf;base64,iVBORw0KGgoAAAANSUhEUgA
AB9AAAAHWCAYAAAAvsRJeAAAABmJLR0QA/wD/AP+gvaeTAAAgAElEQVR4
nOzdaZBd530e¿+WPSXrWLL65dHc1tIPqCdI4YeQHw3t7b7vce8CuII19AJ9IW
7ntht9r+FRMTwQmmnuV+JwPnQHeiRwJxEIkCOgD0tDc9QmTPBrD/BVYqMp
hw/067670rn75OF8MUGHP0x1Dd7c33GqJ5AHZKZ1GjspNBF6Q6muYvXepH
7r2hSDhXxFTxkKC0cz97rC3c1cENADx/6sREvQudL1XmJpVsvByAw8fMRA8DD
49Je6d1L1+rdqPl7qHNP78SJrMwAx1IrDkXRvdMj/H8FtJ7nySqRB+lWfXXfe5c
755xzzjnnnHPOOeecc84555xzzjnnnHPOOeecc84555xzzjnnnHPOOecOgP8A
MOTZaSAigy0AAAAASUVORK5CYII="
}
]
}
• Parámetros de la petición
Parámetro | Descripción | Tipo |
---|---|---|
to | Matriz de direcciones de destinatarios. | Array |
Dirección de correo electrónico del destinatario. | String | |
options | Matriz para incluir direcciones en copia y en copia oculta. | Array |
cc | Dirección de correo electrónico del destinatario en copia. | String |
bcc | Dirección de correo electrónico del destinatario en copia oculta. | String |
subject | Asunto del correo electrónico. | String |
body | Contenido del mensaje en HTML | String |
template_id (opcional) | Código de plantilla de Aldeamo. Encuentre el id de plantilla en su usuario de Aldeamo | String |
Variables (opcional) | Variables personalizadas para ser reemplazadas en el contenido del mensaje | Array |
attachments | Matriz de URL de archivo para enviar como adjunto. | Array |
filename | Reemplaza el nombre de archivo original, si el archivo está codificado en Base64 y este parámetro no está configurado, el archivo se nombrará automáticamente con un nombre aleatorio. | String |
path | URL remota del archivo para enviar como archivo adjunto o archivo URI codificado en Base64. | String |
Esquema de la respuesta exitosa
HTTP/1.1 200 OK
{
"message": "Messages sent!",
"to": [
{
"email": "recipient@exampledomain.com",
"msgid": "40f7f020-4c0c-11e9-870a-51bee176686d"
}
]
}
Parámetros de la respuesta exitosa
Parámetro | Descripción | Tipo |
---|---|---|
Dirección de correo electrónico del destinatario | String | |
msgid | Identificador del mensaje. | String |
Esquema de la respuesta fallida
HTTP/1.1 403 Forbidden
{
"error": "Invalid API Key"
}
Posibles respuestas fallidas
Nombre | Descripción |
---|---|
Invalid_API_Key | La clave de API utilizada no pertenece al usuario o no existe |
API_key_not_authorized | La clave API no estaba autorizada para enviar correos electrónicos |
Current_service_is_not_active | Asegúrese de activar el servicio que desea utilizar en su cuenta |
No_Messages_left | Si el usuario tiene un plan prepago, entonces se ha alcanzado el límite de correo electrónico |
Could_not_find_template | No se encontró la plantilla especificada |
Error_Fetching_Template | No se encontró la plantilla especificada |
Incorrect_variable_syntax | La sintaxis utilizada en el parámetro variable es incorrecta. Recuerda no usar caracteres especiales |
Domain_not_permitted_err_1 | Recuerde utilizar un correo electrónico vinculado a un dominio registrado en su cuenta |
Invalid_request_missing_parameters_err_1 | Error genérico debido a uno o más parámetros faltantes |
Invalid_request_missing_parameters_err_2 | Error genérico debido a uno o más parámetros faltantes |
Missing_replyTo | Campo obligatorio faltante o no válido |
Missing_replyTo_email | Campo obligatorio faltante o no válido |
Missing_replyTo_name | Campo obligatorio faltante o no válido |
Subject_missing_or_empty | Campo vacío o faltante |
Body_missing_or_empty | Campo vacío o faltante |
Recipient_missing_or_empty | Campo vacío o faltante |
A_Recipient_address_is_empty | Si el parámetro de su destinatario es una matriz de direcciones y al menos uno de los elementos falta o no es válido, este mensaje aparecerá. |