Email

Solicitud HTTP para enviar un email

POST https://send.obmessage.ai/api/v1/email
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "to": [
        {
            "email": "string"
        }
    ],
    "options": {
        "cc": [
            {
                "email": "string"
            }
        ],
        "bcc": [
            {
                "email": "string"
            }
        ]
    },
    "from": {
        "email": "string",
        "name": "string"
    },
    "reply_to": {
        "email": "string",
        "name": "string"
    },
    "subject": "string",
    "body": "string",
    "attachments": [
        {
            "path": "string",
            "filename": "string"
        }
    ],
    "reference": "string",
    "group": "string",
    "template_id": "string",
    "not_sent_after": "string",
    "unsubscribe_group_id": 1,
    "fields": [
        {
            "name": "string",
            "value": "string",
            "short": true
        }
    ]
}

Nota

El uso de cc, bcc y reply_to puede no estar disponible en todas las integraciones. Contacte a soporte técnico si necesita habilitar estas opciones.

Importante

Solo se puede enviar un destinatario en to. Si se envía más de un correo, se mostrará el siguiente error:

{
    "code": "error.invalid_payload",
    "message": "cannot send email: currently only 1 'to.email' is allowed"
}

Descripción de los campos

Campo	Descripción	Obligatorio
to	Arreglo de destinatarios.	Sí
to.email	Dirección de correo electrónico del destinatario.	Sí
options	Objeto para incluir direcciones en copia y copia oculta.	No
options.cc	Correo electrónico del destinatario en copia.	No
options.bcc	Correo electrónico del destinatario en copia oculta.	No
from	Datos del emisor del mensaje.	Sí
from.email	Dirección de correo electrónico del emisor. Este campo es opcional si el from está definido en la plantilla.	No
from.name	Nombre del emisor del mensaje.	No
reply_to	Datos asociados a las respuestas del mensaje.	No
reply_to.email	Dirección de correo electrónico que recibirá las respuestas.	Sí
reply_to.name	Nombre asociado a la respuesta.	No
subject	Asunto del correo electrónico.	No
body	Contenido del mensaje en HTML.	No
attachments	Arreglo de URL o archivos en base64 para enviar como adjuntos.	No
attachments.path	URL del archivo o contenido en base64.	Sí
attachments.filename	Nombre del archivo visualizado en la entrega.	Sí
reference	ID de referencia del mensaje.	No
template_id	ID de la plantilla creada. Si se envía este campo, se ignoran body y subject.	No
not_sent_after	Todo mensaje procesado después de la hora indicada se marcará con estado cancelled. El formato de hora debe ser UTC. Este campo no es obligatorio, pero es recomendable para evitar envíos fuera del horario regulado. Ver el apartado de políticas.	No
group	ID de referencia grupal del mensaje.	No
fields	Arreglo de campos dinámicos asociados al mensaje.	No
fields.name	Nombre del campo.	Sí
fields.value	Valor correspondiente al campo.	Sí
fields.short	Indica si el valor del campo será acortado.	No
unsubscribe_group_id	ID del grupo de desuscripción que se asociará al correo enviado.	No

Trama JSON de ejemplo

POST https://send.obmessage.ai/api/v1/email
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "to": [
        {
            "email": "recipient@exampledomain.com"
        }
    ],
    "options": {
        "cc": [
            {
                "email": "cc@exampledomain.com"
            }
        ],
        "bcc": [
            {
                "email": "bcc@exampledomain.com"
            }
        ]
    },
    "from": {
        "email": "sender@yourdomain.com",
        "name": "Sender Name"
    },
    "subject": "Hello World",
    "body": "<h1>Hello World</h1>",
    "attachments": [
        {
            "filename": "reporte1.png",
            "path": "https://obmessage.ai/report.png"
        }
    ],
    "reference": "219012",
    "group": "campid01",
    "template_id": "4fefae9f-7259-4202-ac16-af18df821d74",
    "not_sent_after": "2024-02-12T23:30:59Z",
    "unsubscribe_group_id": 1,
    "fields": [
        {
            "name": "cuota",
            "value": "138.98"
        }
    ]
}

Pruébalo en Postman

Respuesta

Si el mensaje se envía correctamente, se retorna el código 200 OK con la siguiente trama JSON:

{
    "id": "string",
    "to": "string",
    "subject": "string",
    "reference": "string",
    "group": "string",
    "status": "string",
    "created_at": "string"
}

Descripción de los campos de la respuesta

Campo	Descripción
id	Código de identificación del mensaje.
to	Destinatario del mensaje, correspondiente al mismo valor enviado.
subject	Asunto del correo electrónico, correspondiente al mismo valor enviado.
reference	ID de referencia del mensaje, correspondiente al mismo valor enviado.
group	ID de referencia grupal del mensaje, correspondiente al mismo valor enviado.
created_at	Fecha en la que se recibe el mensaje, en formato RFC 3339.
status	Estado actual del mensaje. Los estados son: received y error.

Unsubscribe

Es posible habilitar una función de desuscripción para que los usuarios puedan darse de baja de algunos servicios.

Para esto, debe crear el unsubscribe_group en obm-app, incluyendo los siguientes datos: nombre, descripción y footer. El footer debe contener el texto {{unsubscribe_link}}.

Para enviar el grupo de desuscripción en una notificación, agregue el campo unsubscribe_group_id, cuyo valor se obtiene desde la plataforma de OBMessage. Ver el apartado Trama JSON de ejemplo.