API Documentation

Getting Started

Our Email API is designed to be simple and powerful. Send transactional emails with just a few lines of code.

Base URL
http://mailcurrent.io/api/v1/

Quick Start

  1. Create an account and get your API key
  2. Make a request to our API endpoint
  3. Monitor your email delivery in the dashboard

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Header
X-API-Key: your-api-key-here
Security Note
Keep your API key secure and never expose it in client-side code. Each API key has rate limits and usage tracking.
Email Verification Required
Before you can send emails via the API, you must verify your email address. Unverified users will receive a 405 Method Not Allowed error when attempting to send emails.

Send Custom Email

Send emails with full HTML and text content customization.

POST /send/
Custom Email
Request Body
{
  "to": "[email protected]",
  "subject": "Welcome to our service!",
  "html": "<h1>Welcome!</h1><p>Thank you for joining us.</p>",
  "text": "Welcome! Thank you for joining us.",
  "from_email": "[email protected]",
  "from_name": "Your App",
  "reply_to": "[email protected]",
  "attachments": [
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "mimetype": "application/pdf"
    }
  ]
}
Example Request
curl -X POST http://mailcurrent.io/api/v1/send/ \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Welcome!",
    "html": "<h1>Hello World</h1>",
    "text": "Hello World"
  }'

Send Template Email

Send emails using predefined templates with variable substitution.

POST /send-template/
Template Email
Request Body
{
  "template": "welcome",
  "to": "[email protected]",
  "variables": {
    "user_name": "John Doe",
    "app_name": "MyApp",
    "verification_link": "https://example.com/verify?token=abc123"
  },
  "from_email": "[email protected]",
  "from_name": "Your App"
}
Example Request
curl -X POST http://mailcurrent.io/api/v1/send-template/ \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "welcome",
    "to": "[email protected]",
    "variables": {
      "user_name": "John Doe"
    }
  }'

Email Templates

Pre-built email templates with variable substitution using Jinja2 templating engine.

GET /templates/
List Templates
Example Request
curl -X GET http://mailcurrent.io/api/v1/templates/ \
  -H "X-API-Key: your-api-key"
Response
{
  "success": true,
  "templates": [
    {
      "name": "welcome",
      "subject": "Welcome to !",
      "description": "Welcome email for new users",
      "required_variables": ["user_name", "app_name"],
      "is_active": true,
      "created_at": "2025-10-18T04:07:05.267695Z"
    }
  ]
}

Available Templates

Welcome Template Active
Template Details
  • Name: welcome
  • Subject: Welcome to !
  • Description: Welcome email for new users
  • Required Variables: user_name, app_name
Usage Example
curl -X POST http://mailcurrent.io/api/v1/send-template/ \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "welcome",
    "to": "[email protected]",
    "variables": {
      "user_name": "John Doe",
      "app_name": "MyApp"
    }
  }'
Preview
MailCurrent.io

Welcome to MyApp!

Hello John Doe,

Welcome to MyApp! We're excited to have you on board.

Get started by exploring our features and customizing your experience.

Get Started

Best regards,
The MyApp Team

Verification Template Active
Template Details
  • Name: verification
  • Subject: Verify your email address
  • Description: Email verification template
  • Required Variables: verification_link
Usage Example
curl -X POST http://mailcurrent.io/api/v1/send-template/ \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "verification",
    "to": "[email protected]",
    "variables": {
      "verification_link": "https://myapp.com/verify?token=abc123"
    }
  }'
Preview
MailCurrent.io

Verify Your Email Address

Please click the button below to verify your email address and complete your registration.

Verify Email

If the button doesn't work, copy and paste this link into your browser:
https://myapp.com/verify?token=abc123

Best regards,
The MailCurrent.io Team

Template Variables

All templates support Jinja2 templating with the following common variables:

System Variables
  • - Your site name (MailCurrent.io)
  • - Current date
  • - Current time
  • - Current year
Template-Specific Variables
  • - User's name
  • - Your application name
  • - Email verification URL
  • - Password reset URL
Jinja2 Features

Templates support full Jinja2 syntax including conditionals, loops, and filters. Example: will capitalize the user's name.

Email Logs

View your email sending history and delivery status.

GET /logs/
View Logs
Query Parameters
  • limit - Number of logs to return (default: 50)
  • offset - Number of logs to skip (default: 0)
  • status - Filter by status (sent, failed, pending)
Example Request
curl -X GET "http://mailcurrent.io/api/v1/logs/?limit=10&status=sent" \
  -H "X-API-Key: your-api-key"

Email Tracking

Track email opens and link clicks automatically with our built-in tracking system.

Automatic Tracking

All emails sent through our API automatically include tracking pixels and link tracking. No additional configuration required!

Open Tracking

Every email includes a 1x1 transparent pixel that tracks when the email is opened.

How It Works
  1. Email is sent with a tracking pixel: <img src="https://mailcurrent.io/track/open/{email_id}/{pixel_id}/">
  2. When recipient opens email, pixel loads automatically
  3. Open event is recorded with IP address, user agent, and timestamp
  4. Data appears in your analytics dashboard

Link Click Tracking

All links in your emails are automatically converted to tracking links that redirect to the original destination.

How It Works
  1. Original link: <a href="https://example.com">Visit Site</a>
  2. Automatically converted to: <a href="https://mailcurrent.io/track/click/{email_id}/{link_id}/?url=https%3A//example.com">Visit Site</a>
  3. When clicked, tracks the event and redirects to original URL
  4. Click data includes original URL, IP address, user agent, and timestamp

Tracking Endpoints

These endpoints are used internally by the tracking system and don't require authentication:

GET /track/open/{email_id}/{pixel_id}/
Public

Returns a 1x1 transparent PNG pixel and records the open event.

Response
HTTP/1.1 200 OK
Content-Type: image/png

[1x1 transparent PNG data]
GET /track/click/{email_id}/{link_id}/?url={encoded_url}
Public

Records the click event and redirects to the original URL.

Query Parameters
  • url - The original URL (URL encoded)
Response
HTTP/1.1 302 Found
Location: {original_url}

Excluded Links

The following types of links are automatically excluded from tracking:

  • Unsubscribe links (containing "unsubscribe", "unsub", "opt-out")
  • Protocol links ("mailto:", "tel:")

Tracking Data Structure

Each tracking event includes detailed information about the interaction:

Open Event Data
{
  "event_type": "opened",
  "recipient_email": "[email protected]",
  "email_subject": "Welcome to our service",
  "event_data": {
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "created_at": "2024-01-15T10:30:00Z"
}
Click Event Data
{
  "event_type": "clicked",
  "recipient_email": "[email protected]",
  "email_subject": "Welcome to our service",
  "event_data": {
    "link_id": "abc12345",
    "original_url": "https://example.com/landing-page",
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "timestamp": "2024-01-15T10:35:00Z"
  },
  "created_at": "2024-01-15T10:35:00Z"
}
Privacy Considerations

Tracking data includes IP addresses and user agents. Ensure you comply with privacy regulations like GDPR and CCPA when collecting this data.

Analytics & Reporting

Access detailed analytics about your email campaigns through our dashboard and API.

Dashboard Analytics

View comprehensive analytics in your dashboard at /dashboard/analytics/:

Email Overview
  • • Total emails sent
  • • Open rate percentage
  • • Click rate percentage
  • • Bounce rate percentage
Detailed Reports
  • • Clicked links tracking
  • • Top recipients
  • • Template performance
  • • Recent events timeline

Analytics API Endpoints

GET /api/v1/analytics/
Analytics

Get comprehensive analytics data for your account.

Query Parameters
  • days - Number of days to analyze (default: 30)
Example Request
curl -X GET "http://mailcurrent.io/api/v1/analytics/?days=7" \
  -H "X-API-Key: your-api-key"
Example Response
{
  "overview": {
    "total_emails": 150,
    "sent_emails": 145,
    "failed_emails": 5,
    "opens": 89,
    "clicks": 23,
    "bounces": 2
  },
  "rates": {
    "open_rate": 61.38,
    "click_rate": 15.86,
    "bounce_rate": 1.38
  },
  "daily_breakdown": [...],
  "template_performance": [...],
  "recent_events": [...],
  "top_recipients": [...]
}
GET /api/v1/analytics/clicked-links/
Analytics

Get detailed information about clicked links.

Example Response
{
  "clicked_links": [
    {
      "url": "https://example.com",
      "click_count": 15,
      "unique_clicks": 12,
      "last_clicked": "2024-01-15T10:30:00Z",
      "recipients": ["[email protected]", "[email protected]"]
    }
  ]
}
GET /api/v1/analytics/export/
Export

Export analytics data in CSV or JSON format.

Query Parameters
  • format - Export format: "csv" or "json"
  • days - Number of days to export (default: 30)
Example Request
curl -X GET "http://mailcurrent.io/api/v1/analytics/export/?format=csv&days=7" \
  -H "X-API-Key: your-api-key"

Error Handling

Our API uses standard HTTP status codes and returns detailed error messages.

Status Code Description Example Response
200 Success {"success": true, "message": "Email sent successfully"}
400 Bad Request {"error": "Invalid email address"}
401 Unauthorized {"error": "Invalid or inactive API key"}
405 Method Not Allowed {"error": "Email verification required. Please verify your email address before sending emails via API."}
429 Rate Limited {"error": "Rate limit exceeded"}
500 Server Error {"error": "Internal server error"}