API Documentation

Complete guide to integrating Nefe Mails Email API into your applications

🚀 Quick Start

1. Get Your API Key

Contact us at first@nefetechltd.com to get your API key.

2. Base URL

https://nefe-email-sender-api.onrender.com

3. Authentication

Include your API key in the X-API-Key header:

X-API-Key: your-api-key-here

📡 API Endpoints

POST /api/send_email/

Send an email using your SMTP credentials.

Request Body Parameters

Field Type Required Description
subject string Yes Email subject
recipient string Yes Recipient email address
cc array No CC recipients (max 10 emails) NEW!
bcc array No BCC recipients (max 10 emails) NEW!
attachments array No File attachments (max 5 files, 10MB each, 25MB total) NEW!
body string No Plain text email content
html_body string No HTML email content
smtp_host string Yes SMTP server (e.g., smtp.gmail.com)
smtp_port integer Yes SMTP port (587 for TLS, 465 for SSL)
smtp_username string Yes SMTP username/email
smtp_password string Yes SMTP password
from_email string Yes Sender email address
use_tls boolean No Use TLS encryption (default: true)
use_ssl boolean No Use SSL encryption (default: false)

📧 CC/BCC Support Now Available!

You can now send emails to multiple recipients using CC (Carbon Copy) and BCC (Blind Carbon Copy):

  • Maximum 10 CC recipients
  • Maximum 10 BCC recipients
  • Total recipients (to + cc + bcc) must not exceed 20
  • Both fields are optional and fully backward compatible

📎 Email Attachments Support!

You can now send emails with file attachments using Base64 encoding:

  • Maximum 5 attachments per email
  • Maximum 10MB per individual file
  • Maximum 25MB total size for all attachments
  • Supported file types: PDF, DOC, DOCX, TXT, PNG, JPG, JPEG, GIF, ZIP, CSV, XLSX
  • Format: Each attachment must include filename and content (Base64 encoded)
  • Optional: This field is optional - existing integrations continue to work without changes
GET /api/health/

Check if the API is running and accessible.

💻 Code Examples

Python with Requests

send_email.py 
import requests
import base64

# API Configuration
API_URL = "https://nefe-email-sender-api.onrender.com/api/send_email/"
API_KEY = "your-api-key-here"

# Read and encode file (optional)
with open("document.pdf", "rb") as file:
    file_content = base64.b64encode(file.read()).decode("utf-8")

# Email Configuration
payload = {
    "subject": "Hello from Python!",
    "recipient": "recipient@example.com",
    "cc": ["manager@example.com", "team@example.com"],  # Optional
    "bcc": ["archive@example.com"],  # Optional
    "body": "This is a test email sent using Python.",
    "html_body": "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
    "attachments": [  # Optional - max 5 files, 10MB each, 25MB total
        {
            "filename": "document.pdf",
            "content": file_content
        }
    ],
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "your-email@gmail.com",
    "smtp_password": "your-app-password",
    "from_email": "your-email@gmail.com",
    "use_tls": True,
    "use_ssl": False
}

# Send Request
headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

response = requests.post(API_URL, json=payload, headers=headers)

# Handle Response
if response.status_code == 200:
    print("✅ Email sent successfully!")
    print(response.json())
else:
    print(f"❌ Error: {response.status_code}")
    print(response.json())

JavaScript with Fetch API

send_email.js 
// API Configuration
const API_URL = "https://nefe-email-sender-api.onrender.com/api/send_email/";
const API_KEY = "your-api-key-here";

// Email Configuration
const payload = {
  subject: "Hello from JavaScript!",
  recipient: "recipient@example.com",
  cc: ["manager@example.com", "team@example.com"],  // Optional
  bcc: ["archive@example.com"],  // Optional
  body: "This is a test email sent using JavaScript.",
  html_body: "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
  attachments: [  // Optional - max 5 files, 10MB each, 25MB total
    {
      filename: "report.pdf",
      content: "base64-encoded-content-here"
    }
  ],
  smtp_host: "smtp.gmail.com",
  smtp_port: 587,
  smtp_username: "your-email@gmail.com",
  smtp_password: "your-app-password",
  from_email: "your-email@gmail.com",
  use_tls: true,
  use_ssl: false
};

// Send Request
fetch(API_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log("✅ Email sent successfully!");
    console.log(data);
  })
  .catch(error => {
    console.error("❌ Error:", error);
  });

PHP with cURL

send_email.php 
<?php
// API Configuration
$apiUrl = "https://nefe-email-sender-api.onrender.com/api/send_email/";
$apiKey = "your-api-key-here";

// Email Configuration
$payload = [
    "subject" => "Hello from PHP!",
    "recipient" => "recipient@example.com",
    "cc" => ["manager@example.com", "team@example.com"],  // Optional
    "bcc" => ["archive@example.com"],  // Optional
    "body" => "This is a test email sent using PHP.",
    "html_body" => "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
    "smtp_host" => "smtp.gmail.com",
    "smtp_port" => 587,
    "smtp_username" => "your-email@gmail.com",
    "smtp_password" => "your-app-password",
    "from_email" => "your-email@gmail.com",
    "use_tls" => true,
    "use_ssl" => false
];

// Initialize cURL
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-Key: $apiKey"
]);

// Execute Request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Handle Response
if ($httpCode == 200) {
    echo "✅ Email sent successfully!\n";
    echo $response;
} else {
    echo "❌ Error: $httpCode\n";
    echo $response;
}
?>

Ruby with Net::HTTP

send_email.rb 
require 'net/http'
require 'json'
require 'uri'

# API Configuration
api_url = URI("https://nefe-email-sender-api.onrender.com/api/send_email/")
api_key = "your-api-key-here"

# Email Configuration
payload = {
  subject: "Hello from Ruby!",
  recipient: "recipient@example.com",
  cc: ["manager@example.com", "team@example.com"],  # Optional
  bcc: ["archive@example.com"],  # Optional
  body: "This is a test email sent using Ruby.",
  html_body: "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
  smtp_host: "smtp.gmail.com",
  smtp_port: 587,
  smtp_username: "your-email@gmail.com",
  smtp_password: "your-app-password",
  from_email: "your-email@gmail.com",
  use_tls: true,
  use_ssl: false
}

# Send Request
http = Net::HTTP.new(api_url.host, api_url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(api_url)
request["Content-Type"] = "application/json"
request["X-API-Key"] = api_key
request.body = payload.to_json

response = http.request(request)

# Handle Response
if response.code == "200"
  puts "✅ Email sent successfully!"
  puts response.body
else
  puts "#{response.code}"
  puts response.body
end

Go with net/http

send_email.go 
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    // API Configuration
    apiURL := "https://nefe-email-sender-api.onrender.com/api/send_email/"
    apiKey := "your-api-key-here"

    // Email Configuration
    payload := map[string]interface{}{
        "subject":       "Hello from Go!",
        "recipient":     "recipient@example.com",
        "cc":            []string{"manager@example.com", "team@example.com"},  // Optional
        "bcc":           []string{"archive@example.com"},  // Optional
        "body":          "This is a test email sent using Go.",
        "html_body":     "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
        "smtp_host":     "smtp.gmail.com",
        "smtp_port":     587,
        "smtp_username": "your-email@gmail.com",
        "smtp_password": "your-app-password",
        "from_email":    "your-email@gmail.com",
        "use_tls":       true,
        "use_ssl":       false,
    }

    // Marshal payload
    jsonData, err := json.Marshal(payload)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    // Create request
    req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    // Send request
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    // Read response
    body, _ := ioutil.ReadAll(resp.Body)

    if resp.StatusCode == 200 {
        fmt.Println("✅ Email sent successfully!")
        fmt.Println(string(body))
    } else {
        fmt.Printf("❌ Error: %d\n", resp.StatusCode)
        fmt.Println(string(body))
    }
}

cURL Command

bash 
curl -X POST https://nefe-email-sender-api.onrender.com/api/send_email/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "subject": "Hello from cURL!",
    "recipient": "recipient@example.com",
    "cc": ["manager@example.com", "team@example.com"],
    "bcc": ["archive@example.com"],
    "body": "This is a test email sent using cURL.",
    "html_body": "<h1>Hello!</h1><p>This is a <strong>test email</strong>.</p>",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "your-email@gmail.com",
    "smtp_password": "your-app-password",
    "from_email": "your-email@gmail.com",
    "use_tls": true,
    "use_ssl": false
  }'

📊 Response Examples

Success Response (200 OK) 

{
  "status": "success",
  "message": "Email sent successfully to recipient@example.com",
  "response_time": 2.45
}

Basic email without CC/BCC

Success Response with CC/BCC (200 OK) NEW! 

{
  "status": "success",
  "message": "Email sent successfully to recipient@example.com (+ 3 CC/BCC)",
  "response_time": 2.87,
  "recipients": {
    "to": "recipient@example.com",
    "cc_count": 2,
    "bcc_count": 1,
    "total": 4
  }
}

When using CC/BCC, you get recipient count breakdown

Error Response (400 Bad Request) 

{
  "status": "error",
  "message": "Invalid email address format",
  "response_time": 0.12
}

Authentication Error (401 Unauthorized) 

{
  "status": "error",
  "message": "Invalid API key",
  "response_time": 0.08
}

⚠️ Error Codes

Code Message Solution
400 Invalid request data Check your request payload
401 Invalid API key Verify your API key
403 Rate limit exceeded Wait before retrying
500 SMTP connection failed Check SMTP credentials
503 Service unavailable Try again later

✨ Best Practices

Secure Your API Key

Never expose your API key in client-side code. Use environment variables.

Validate Email Addresses

Always validate recipient email addresses before sending requests.

Handle Rate Limits

Implement exponential backoff when rate limits are reached.

Log Responses

Keep logs of API responses for debugging and monitoring.