Email¶

Antes de comenzar¶

Prepare el destinatario, el remitente y el contenido o plantilla. Esta API permite un destinatario en to; no aplique a este endpoint el límite de destinatarios de SMTP. Si envía template_id, se ignoran body y subject.

Revise Autenticación y sustituya los valores de ejemplo, incluidos los IDs de plantilla y las fechas, antes de ejecutar una solicitud.

Secuencia de la solicitud¶

Prepare la solicitud HTTP indicada a continuación.
Complete los campos requeridos y solo los opcionales que necesite su integración.
Ejecute la solicitud y revise la respuesta.
Conserve el identificador retornado, cuando exista, y compruebe el resultado antes de repetir un envío.

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¶

Los campos anidados obligatorios aplican cuando se incluye el objeto o elemento del arreglo que los contiene.

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¶

El endpoint retorna 200 OK con la siguiente respuesta JSON. Revise status; esta respuesta no confirma por sí sola la entrega al destinatario.

{
    "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.

Consultar resultados y errores¶

Utilice el id recibido en Consultar estado. Conserve la referencia y el grupo utilizados por la integración para localizar los registros. Ante solicitudes fallidas, consulte Respuestas de error.