Send Email
Send manual emails with attachments and call-to-action buttons. Supports bulk sending with automatic throttling.
curl -X POST https://your-api.com/api/settings/sendmail \
-H "Authorization: Bearer YOUR_TOKEN" \
-F 'to=["[email protected]"]' \
-F 'subject=Service Update' \
-F 'body=Your service request has been completed successfully.' \
-F 'ctaUrl=https://example.com/request/123' \
-F 'ctaText=View Request'
Request Body (multipart/form-data)
Email message body (plain text or HTML)
Call-to-action button URL (optional)
Call-to-action button text (optional, defaults to “Learn More”)
Image attachments (max 5 files, 10MB each, images only)
Response (Normal Send)
Normal Send (≤3 recipients)
Response (Bulk Send with Throttling)
Bulk Send (>3 recipients)
{
"success": true,
"message": "Envío masivo iniciado para 10 destinatario(s). Los correos se enviarán de forma gradual.",
"recipients": [
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]"
],
"mail_id": 457,
"attachments_count": 0,
"bulk_mode": true,
"estimated_time_seconds": 15
}
Bulk Send Throttling: When sending to more than 3 recipients, the system uses throttling to prevent email server overload:
- Batch size: 2 emails per batch
- Delay: 5 seconds between batches
- Response: Immediate (processing happens in background)
- Status: Check
mail-history/:id endpoint for final status
Attachment Processing
Attachments are:
- Uploaded to S3 with keys like
mail-attachments/{timestamp}_{filename}
- Stored in database with metadata (filename, size, content_type, s3_key)
- Attached to emails as inline attachments
Error Responses
{
"success": false,
"error": "Se requiere al menos un destinatario"
}
{
"success": false,
"error": "El asunto es requerido"
}
{
"success": false,
"error": "Error al enviar el correo",
"details": "SMTP connection failed",
"mail_id": 458
}
Get Email History
List all sent emails with filtering and pagination.
curl -X GET "https://your-api.com/api/settings/mail-history?limit=20&offset=0&status=sent" \
-H "Authorization: Bearer YOUR_TOKEN"
Query Parameters
Number of records to return (max 100)
Number of records to skip (for pagination)
Filter by status: pending, sending, sent, failed, or partial
Search in recipients, subject, or body
Response
Array of email history records
Total count of matching records
{
"success": true,
"mails": [
{
"mail_id": 456,
"recipients": ["[email protected]", "[email protected]"],
"subject": "Service Update",
"body": "Your service request has been completed.",
"cta_url": "https://example.com/request/123",
"cta_text": "View Request",
"status": "sent",
"error_message": null,
"attachments": [
{
"filename": "invoice.pdf",
"size": 45678,
"content_type": "application/pdf",
"s3_key": "mail-attachments/1709467200000_invoice.pdf",
"url": "https://s3.amazonaws.com/bucket/mail-attachments/1709467200000_invoice.pdf?X-Amz-Signature=..."
}
],
"sent_by": 1,
"sent_by_name": "Admin User",
"created_at": "2026-03-03T10:30:00Z",
"total_count": 150
}
],
"total": 150,
"limit": 20,
"offset": 0
}
Email Status Values
Email queued but not yet sent (normal send)
Bulk send in progress (background processing)
Successfully sent to all recipients
Failed to send to all recipients
Sent to some recipients but failed for others (bulk send)
Get Email Details
Get detailed information about a specific email.
curl -X GET https://your-api.com/api/settings/mail-history/456 \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
{
"success": true,
"mail": {
"mail_id": 456,
"recipients": ["[email protected]"],
"subject": "Service Update",
"body": "Your service request has been completed successfully.",
"cta_url": "https://example.com/request/123",
"cta_text": "View Request",
"status": "sent",
"error_message": null,
"attachments": [
{
"filename": "service-report.png",
"size": 123456,
"content_type": "image/png",
"s3_key": "mail-attachments/1709467200000_service-report.png",
"url": "https://s3.amazonaws.com/bucket/...?X-Amz-Signature=..."
}
],
"sent_by": 1,
"sent_by_name": "Admin User",
"created_at": "2026-03-03T10:30:00Z",
"updated_at": "2026-03-03T10:30:15Z"
}
}
Error Response
{
"success": false,
"error": "Correo no encontrado"
}
Email Template
Emails are sent using the generic template with the following structure:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{heading}}</title>
</head>
<body>
<h1>{{heading}}</h1>
<div class="message">
{{message}}
</div>
{{#if ctaUrl}}
<a href="{{ctaUrl}}" class="cta-button">
{{ctaText}}
</a>
{{/if}}
<footer>
Ambiotec - Professional Services
</footer>
</body>
</html>
Template Variables
heading: Subject line (also used as email heading)message: Email body contentctaUrl: Optional call-to-action URLctaText: Optional call-to-action button text