> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opptima.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Enviar Email
> Envía correos electrónicos a uno o múltiples destinatarios.
Puedes enviar emails de dos formas:
- **Con HTML directo**: Incluye el contenido HTML en el campo `body`
- **Con plantilla**: Usa `template_id` y pasa variables dinámicas
### Características
- Soporte para CC y BCC
- Múltiples adjuntos (URLs remotas o Base64)
- Reemplazo de variables en plantillas
## OpenAPI
````yaml /api-reference/openapi.yaml post /v1/email
openapi: 3.1.0
info:
title: Opptima API
version: 1.0.0
description: >
API para acceder a las funcionalidades de Opptima programáticamente.
## Autenticación
Todas las solicitudes requieren un API Key que debes incluir en el header
`Authorization` como Bearer token.
Para obtener tu API Key, ve a
[Settings](https://app.opptima.com/es/settings).
## Rate Limiting
La API implementa límites de tasa para proteger el servicio:
- **Límite por defecto**: 2 peticiones por segundo (o 2 segundos por
request)
- Este límite es **ampliable bajo requerimiento**
Si necesitas un límite mayor para tu caso de uso, contacta a soporte.
contact:
name: Opptima Support
email: support@opptima.com
license:
name: Proprietary
servers:
- url: https://api.ckpnd.com:5001
description: Servidor principal (HTTPS)
security:
- bearerAuth: []
tags:
- name: Email
description: Envío de correos electrónicos transaccionales y con plantillas
x-page-icon: envelope
x-page-description: Envía emails con HTML, plantillas, adjuntos y certificación
- name: Templates
description: Gestión de plantillas de correo electrónico
x-page-icon: file-text
x-page-description: Obtiene plantillas de email disponibles en tu cuenta
- name: SMS
description: Envío de mensajes SMS
x-page-icon: mobile
x-page-description: Envía mensajes SMS a múltiples destinatarios
- name: WhatsApp
description: Envío de mensajes de WhatsApp
x-page-icon: whatsapp
x-page-description: Envía mensajes de WhatsApp usando plantillas o mensajes de sesión
- name: Email Marketing
description: >
Eventos webhook generados por campañas de Email Marketing.
Estos eventos son enviados como POST a la URL de webhook configurada en tu
cuenta.
x-page-icon: bell
x-page-description: >-
Eventos de entrega, rebote, apertura, click, desuscripción y queja para
Email Marketing
- name: SMTP
description: >
Eventos webhook generados por mensajes transaccionales SMTP/API.
Estos eventos son enviados como POST a la URL de webhook configurada en tu
cuenta.
Algunos campos no están disponibles para emails certificados.
x-page-icon: bell
x-page-description: >-
Eventos de entrega, rebote, apertura, click, entrega certificada y
desuscripción para SMTP/API
paths:
/v1/email:
post:
tags:
- Email
summary: Enviar Email
description: |
Envía correos electrónicos a uno o múltiples destinatarios.
Puedes enviar emails de dos formas:
- **Con HTML directo**: Incluye el contenido HTML en el campo `body`
- **Con plantilla**: Usa `template_id` y pasa variables dinámicas
### Características
- Soporte para CC y BCC
- Múltiples adjuntos (URLs remotas o Base64)
- Reemplazo de variables en plantillas
operationId: sendEmail
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- to
- from
- replyTo
- subject
properties:
to:
type: array
description: Array de destinatarios
items:
type: object
required:
- email
properties:
email:
type: string
format: email
example: recipient@exampledomain.com
options:
type: object
description: Opciones de CC y BCC
properties:
cc:
type: array
description: Destinatarios en copia (Carbon Copy)
items:
type: object
required:
- email
properties:
email:
type: string
format: email
bcc:
type: array
description: Destinatarios en copia oculta (Blind Carbon Copy)
items:
type: object
required:
- email
properties:
email:
type: string
format: email
from:
type: object
description: >-
Dirección del remitente. El dominio debe estar verificado en
tu cuenta
required:
- email
- name
properties:
email:
type: string
format: email
example: sender@yourdomain.com
name:
type: string
example: John Doe
replyTo:
type: object
description: Dirección de respuesta
required:
- email
- name
properties:
email:
type: string
format: email
example: sender@yourdomain.com
name:
type: string
example: John Doe
subject:
type: string
description: Asunto del correo
example: Hello World
body:
type: string
description: >-
Contenido HTML o texto plano del mensaje (no requerido si
usas template_id)
example: Hello World
template_id:
type: string
description: >-
ID de la plantilla a usar (encuentra el ID en tu página de
plantillas)
example: 42eqy7oaigql
variables:
type: object
description: >-
Variables para reemplazar en la plantilla. Evita caracteres
especiales en los nombres
additionalProperties:
type: string
example:
variable1: random variable 1
variable2: random variable 2
attachments:
type: array
description: Array de archivos adjuntos
items:
type: object
required:
- filename
- path
properties:
filename:
type: string
description: Nombre del archivo con su extensión
example: file1.pdf
path:
type: string
description: >-
URL remota del archivo o archivo codificado en Base64
URI
example: https://example.com/file.pdf
examples:
htmlBody:
summary: Email con HTML
value:
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: Hello World
attachments:
- filename: file1.gif
path: >-
https://i1.wp.com/cms.babbel.news/wp-content/uploads/2015/05/HEAD02_FRA-20150703094705.gif
- filename: file2.jpg
path: >-
http://2.bp.blogspot.com/-DIEPOOz9uqI/UHomvta-AcI/AAAAAAAAAdI/_Nv0WyIXxhA/s1600/P1010411.JPG
withTemplate:
summary: Email con plantilla
value:
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/wp-content/uploads/2015/05/HEAD02_FRA-20150703094705.gif
- filename: pdf1.pdf
path: data:application/pdf;base64,iVBORw0KGgoAAAANSUhEUg...
responses:
'200':
description: Mensaje enviado exitosamente
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Messages sent!
to:
type: array
items:
type: object
properties:
email:
type: string
format: email
msgid:
type: string
description: ID único del mensaje
examples:
success:
value:
message: Messages sent!
to:
- email: recipient@exampledomain.com
msgid: 40f7f020-4c0c-11e9-870a-51bee176686d
'400':
description: >
Parámetros faltantes o inválidos. Posibles errores incluyen
validaciones
de direcciones (from, to, cc, bcc, replyTo), asunto, cuerpo del
mensaje,
plantillas, variables y adjuntos.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/ValidationError'
examples:
missingFrom:
summary: Falta dirección del remitente
value:
message: Missing from address!
fromWrongStructure:
summary: Estructura de dirección from inválida
value:
message: The from address has the wrong structure!
error:
- email: sender<@yourdomain.com
missingReplyTo:
summary: Falta replyTo
value:
message: Missing replyTo!
missingReplyToName:
summary: Falta nombre de replyTo
value:
message: Missing replyTo name!
missingReplyToEmail:
summary: Falta email de replyTo
value:
message: Missing replyTo email!
replyToWrongStructure:
summary: Estructura de dirección replyTo inválida
value:
message: The replyTo address has the wrong structure!
subjectMissing:
summary: Asunto faltante o vacío
value:
message: Subject missing or empty!
bodyMissing:
summary: Cuerpo del mensaje faltante o vacío
value:
message: Body missing or empty!
recipientMissing:
summary: Destinatario faltante o vacío
value:
message: Recipient missing or empty!
noRecipients:
summary: Sin destinatarios definidos
value:
message: No recipients defined
addresseesNotDefined:
summary: Algunos destinatarios no están definidos
value:
message: Some addressees have not been defined
recipientAddressEmpty:
summary: Una dirección de destinatario está vacía
value:
message: a Recipient address is empty!
recipientWrongStructure:
summary: Estructura de dirección de destinatario inválida
value:
message: The recipient address has the wrong structure!
error:
- email: recipient<@exampledomain.com
- email: recipient2 @exampledomain.com
ccWrongStructure:
summary: Estructura de dirección CC inválida
value:
message: The cc address has the wrong structure!
error:
- email: cc<@exampledomain.com
bccWrongStructure:
summary: Estructura de dirección BCC inválida
value:
message: The bcc address has the wrong structure!
error:
- email: bcc<@exampledomain.com
templateNotFound:
summary: Plantilla no encontrada
value:
message: Could not find template
incorrectVariableSyntax:
summary: Sintaxis de variable incorrecta
value:
message: Incorrect variable syntax
errorFetchingTemplate:
summary: Error al obtener plantilla
value:
message: Error Fetching Template
attachmentsNotArray:
summary: Parámetro attachments no es un array
value:
message: Attachments parameter is set but is not an array
attachmentsMissingFilename:
summary: Falta filename en adjuntos
value:
message: >-
One or many attachments are missing the filename parameter
which is mandatory for each attachment
attachmentsMissingPath:
summary: Falta path en adjuntos
value:
message: >-
One or many attachments are missing the path parameter,
which is mandatory for each attachment and must be a
base64 URI encoded file
couldNotSendMessage:
summary: Error al enviar mensaje
value:
message: Could not send message, an error has ocurred
invalidRequestErr1:
summary: Error genérico por parámetros faltantes
value:
message: Invalid request, missing parameters. err 1
invalidRequestErr2:
summary: Error genérico por parámetros faltantes
value:
message: Invalid request, missing parameters. err 2
'401':
description: >-
API key no autorizada, servicio inactivo, sin mensajes disponibles,
o dominio no permitido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notAuthorized:
summary: API key no autorizada para enviar emails
value:
message: API key not authorized.
serviceInactive:
summary: El servicio no está activo
value:
message: current service is not active
noMessagesLeft:
summary: Sin mensajes disponibles (plan prepago)
value:
message: No messages left, please buy more messages
domainNotPermitted:
summary: Dominio del remitente no verificado
value:
message: Domain not permitted. err 2
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/MiddlewareError'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
description: Respuesta de error estándar de la aplicación
properties:
message:
type: string
description: Descripción del error
required:
- message
ValidationError:
type: object
description: >-
Respuesta de error con detalle de validación (por ejemplo, direcciones
con estructura inválida)
properties:
message:
type: string
description: Descripción del error
error:
type: array
description: Detalle de los elementos que causaron el error
items:
type: object
properties:
email:
type: string
description: Dirección de email con estructura inválida
required:
- message
AuthError:
type: object
description: Respuesta de error de autenticación del middleware
properties:
error:
type: string
description: Descripción del error de autenticación
required:
- error
RateLimitError:
type: object
description: Respuesta cuando se excede el límite de peticiones por segundo
properties:
success:
type: boolean
example: false
message:
type: string
example: Ha excedido el límite de peticiones permitidas por segundo.
error:
type: string
example: RATE_LIMIT_EXCEEDED
required:
- success
- message
- error
responses:
Forbidden:
description: |
Error de autenticación. La API Key no fue enviada, es inválida, o la IP
de origen no está permitida en la lista blanca configurada.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthError'
examples:
noApiKey:
summary: API Key no enviada en el header Authorization
value:
error: No API Key sent
invalidApiKey:
summary: API Key inválida o no encontrada
value:
error: 'Invalid API Key '
ipNotAllowed:
summary: IP de origen no permitida
value:
error: 'IP Not Allowed '
RateLimited:
description: >
Se ha excedido el límite de peticiones por segundo.
El límite por defecto es de 2 peticiones por segundo y es ampliable bajo
requerimiento.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
rateLimited:
value:
success: false
message: Ha excedido el límite de peticiones permitidas por segundo.
error: RATE_LIMIT_EXCEEDED
MiddlewareError:
description: Error interno del servidor durante la validación de autenticación
content:
application/json:
schema:
$ref: '#/components/schemas/AuthError'
examples:
middlewareError:
value:
error: >-
An error has ocurred, please try again. Contact us if the
issue persists
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Usa tu API Key como Bearer token en el header Authorization.
Ejemplo: `Authorization: Bearer YOUR_API_KEY`
Obtén tu API Key en la [página de
Settings](https://app.opptima.com/es/settings).
````