Overview

The Email API provides a simple way to send emails with HTML content, attachments, and advanced features. All emails are sent through the Resend service for optimal deliverability.

Send Single Email

Request Body

Example Request (HTML Email)

curl -X POST https://uconect.ulibtech.org/api/email/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "to": "customer@example.com",
    "subject": "Welcome to Our Service!",
    "html": "
Welcome!
Thank you for signing up.
",
    "from": "hello@yourdomain.com",
    "reply_to": "support@yourdomain.com",
    "tags": [
      {"name": "category", "value": "welcome"}
    ]
  }'

const response = await fetch('https://uconect.ulibtech.org/api/email/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Welcome to Our Service!',
    html: '
Welcome!
Thank you for signing up.
',
    from: 'hello@yourdomain.com',
    reply_to: 'support@yourdomain.com',
    tags: [
      {name: 'category', value: 'welcome'}
    ]
  })
});

const result = await response.json();
console.log(result);

import requests

url = 'https://uconect.ulibtech.org/api/email/send'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
}
data = {
    'to': 'customer@example.com',
    'subject': 'Welcome to Our Service!',
    'html': '
Welcome!
Thank you for signing up.
',
    'from': 'hello@yourdomain.com',
    'reply_to': 'support@yourdomain.com',
    'tags': [
        {'name': 'category', 'value': 'welcome'}
    ]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Success Response

{
  "success": true,
  "email_id": "abc123def456",
  "cost": 0.10,
  "response": {
    "id": "abc123def456"
  }
}

Example with Attachments

{
  "to": "customer@example.com",
  "subject": "Your Invoice",
  "html": "
Please find your invoice attached.
",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "base64_encoded_content_here"
    }
  ]
}

Send Bulk Email

Request Body

Email Object Fields

Each email object should contain the same fields as single email send (to, subject, html/text, etc.)

Example Request

curl -X POST https://uconect.ulibtech.org/api/email/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "from": "newsletter@yourdomain.com",
    "emails": [
      {
        "to": "user1@example.com",
        "subject": "Monthly Newsletter",
        "html": "
This Month Updates
Content here...
"
      },
      {
        "to": "user2@example.com",
        "subject": "Monthly Newsletter",
        "html": "
This Month Updates
Content here...
"
      },
      {
        "to": "user3@example.com",
        "subject": "Special Offer",
        "html": "
Exclusive Deal
Get 50% off...
"
      }
    ]
  }'

Success Response

{
  "success": true,
  "batch_id": "batch_1703501234567",
  "total": 3,
  "sent": 3,
  "failed": 0,
  "cost": 0.30,
  "results": [
    {
      "recipient": "user1@example.com",
      "success": true,
      "email_id": "email_001",
      "error": null
    },
    {
      "recipient": "user2@example.com",
      "success": true,
      "email_id": "email_002",
      "error": null
    },
    {
      "recipient": "user3@example.com",
      "success": true,
      "email_id": "email_003",
      "error": null
    }
  ]
}

View Email Logs

Query Parameters

Example Request

curl -X GET "https://uconect.ulibtech.org/api/email/logs?status=sent&limit=20" \
  -H "X-API-Key: your_api_key_here"

Response

{
  "success": true,
  "logs": [
    {
      "id": 1,
      "email_id": "abc123def456",
      "recipient": "customer@example.com",
      "subject": "Welcome to Our Service!",
      "from_email": "hello@yourdomain.com",
      "status": "sent",
      "cost": 0.10,
      "batch_id": null,
      "sent_at": "2024-12-25T10:30:00Z",
      "created_at": "2024-12-25T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 250,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

HTML Email Templates

Here are some best practices for creating HTML emails:

Basic Template

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Email Title</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      line-height: 1.6;
      color: #333;
      max-width: 600px;
      margin: 0 auto;
      padding: 20px;
    }
    .header {
      background: #4CAF50;
      color: white;
      padding: 20px;
      text-align: center;
    }
    .content {
      padding: 20px;
      background: #f9f9f9;
    }
    .button {
      display: inline-block;
      padding: 12px 24px;
      background: #4CAF50;
      color: white;
      text-decoration: none;
      border-radius: 4px;
    }
    .footer {
      text-align: center;
      padding: 20px;
      color: #666;
      font-size: 12px;
    }
  </style>
</head>
<body>
  <div class="header">
    <h1>Your Company Name</h1>
  </div>
  
  <div class="content">
    <h2>Hello {{name}}!</h2>
    <p>Your email content goes here.</p>
    <p>
      <a href="{{action_url}}" class="button">Take Action</a>
    </p>
  </div>
  
  <div class="footer">
    <p>© 2024 Your Company. All rights reserved.</p>
    <p>
      <a href="{{unsubscribe_url}}">Unsubscribe</a>
    </p>
  </div>
</body>
</html>

Template Best Practices

• ✅ Use inline CSS for better compatibility
• ✅ Keep width under 600px for mobile
• ✅ Use tables for complex layouts
• ✅ Always include plain text alternative
• ✅ Test across multiple email clients
• ✅ Include unsubscribe links for marketing emails

Validation Rules

Email Address

• Must be valid email format
• Example: user@example.com
• Multiple recipients: array format

Subject Line

• Maximum: 200 characters
• Avoid spam trigger words
• Be clear and descriptive

Content Requirements

• Either HTML or plain text required
• HTML: Properly formatted HTML5
• Text: Plain text alternative
• Recommended: Include both for best compatibility

Attachments

• Must be base64 encoded
• Include filename and content
• Common types: PDF, images, documents

Common Error Responses

Email Service Not Configured

{
  "error": "Email service not configured. Please contact administrator."
}

Insufficient Credits

{
  "error": "Insufficient credits",
  "required": 0.10,
  "available": 0.05
}

Validation Failed

{
  "error": "Validation failed",
  "details": [
    "Recipient email is required",
    "Subject is required",
    "Either HTML or text content is required"
  ]
}

Batch Limit Exceeded

{
  "error": "Batch limit exceeded. Maximum 50 emails allowed."
}

💡 Best Practices