Web Service Rest tipo POST

//Web Service Rest tipo POST

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
email 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
email 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á.
2021-06-24T15:25:55-05:00