API Documentation

Overview

The MailEnv Public API provides email functionality with API key authentication. All endpoints require a valid API key in the Authorization header.

Authentication

All API endpoints require authentication using an API key. Include your key in the Authorization header for each request.

Header format

Authorization: your-api-key-here

Endpoints

• Send Mail — send a transactional email.

Send Mail

Sends an email message using the provided parameters.

Request Headers

Request Body

Request Example

curl -X POST "https://pub-api.mailenv.com/api/v1/send-mail" \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "from": "sender@example.com",
    "subject": "Test Email",
    "message": "This is a test email message"
  }'

Responses

201 Created — Mail Request Successful

{
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

400 Bad Request — Missing Required Fields

{
  "result": "error",
  "message": "Missing required fields: to, subject"
}

400 Bad Request — Invalid JSON

{
  "result": "error",
  "message": "Invalid JSON payload"
}

401 Unauthorized — Invalid API Key

{
  "result": "error",
  "message": "Invalid API key"
}

401 Unauthorized — Account Locked

{
  "result": "error",
  "message": "Account locked"
}

403 Forbidden — Invalid Tokens / Rate Limit

{
  "result": "error",
  "message": "Invalid tokens or rate limit exceeded"
}

Response Fields

Notes

• All email addresses should be in valid email format.
• The API key must be active and not locked for the request to succeed.

Error Codes

Code Examples

Python — requests

import requests
import json

API_KEY = "your-api-key-here"
BASE_URL = "https://pub-api.mailenv.com"
ENDPOINT = "/api/v1/send-mail"

mail_data = {
    "to": "recipient@example.com",
    "from": "sender@example.com",
    "subject": "Test Email",
    "message": "This is a test email message"
}

headers = {
    "Authorization": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}{ENDPOINT}",
    headers=headers,
    json=mail_data
)

if response.status_code == 201:
    result = response.json()
    print(f"✅ Email sent successfully! ID: {result['result']['id']}")
else:
    error = response.json()
    print(f"❌ Error: {error['message']}")

Python — httpx (async)

import httpx
import asyncio

async def send_email():
    API_KEY = "your-api-key-here"
    BASE_URL = "https://pub-api.mailenv.com"

    mail_data = {
        "to": "recipient@example.com",
        "from": "sender@example.com",
        "subject": "Test Email",
        "message": "This is a test email message"
    }

    headers = {
        "Authorization": API_KEY,
        "Content-Type": "application/json"
    }

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{BASE_URL}/api/v1/send-mail",
            headers=headers,
            json=mail_data
        )

        if response.status_code == 201:
            result = response.json()
            print(f"✅ Email sent! ID: {result['result']['id']}")
        else:
            error = response.json()
            print(f"❌ Error: {error['message']}")

asyncio.run(send_email())

JavaScript — fetch

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://pub-api.mailenv.com';

const mailData = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  message: 'This is a test email message'
};

async function sendEmail() {
  try {
    const res = await fetch(`${BASE_URL}/api/v1/send-mail`, {
      method: 'POST',
      headers: {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(mailData)
    });
    const result = await res.json();
    if (res.status === 201) console.log(`✅ Email sent! ID: ${result.result.id}`);
    else console.log(`❌ Error: ${result.message}`);
  } catch (e) {
    console.error('❌ Request failed:', e);
  }
}
sendEmail();

JavaScript — axios

import axios from 'axios';

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://pub-api.mailenv.com';

const mailData = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  message: 'This is a test email message'
};

async function sendEmail(){
  try {
    const res = await axios.post(`${BASE_URL}/api/v1/send-mail`, mailData, {
      headers: {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
      }
    });
    console.log(`✅ Email sent successfully! ID: ${res.data.result.id}`);
  } catch (error) {
    if (error.response) console.log(`❌ Error: ${error.response.data.message}`);
    else console.error('❌ Request failed:', error.message);
  }
}
sendEmail();

Node — node-fetch (CJS)

const fetch = require('node-fetch');

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://pub-api.mailenv.com';

const mailData = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  message: 'This is a test email message'
};

(async function(){
  try {
    const res = await fetch(`${BASE_URL}/api/v1/send-mail`, {
      method: 'POST',
      headers: {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(mailData)
    });
    const result = await res.json();
    if (res.status === 201) console.log(`✅ Email sent successfully! ID: ${result.result.id}`);
    else console.log(`❌ Error: ${result.message}`);
  } catch (e) {
    console.error('❌ Request failed:', e);
  }
})();

Go — net/http

package main

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

type MailData struct {
  To      string `json:"to"`
  From    string `json:"from"`
  Subject string `json:"subject"`
  Message string `json:"message"`
}

type ApiResponse struct {
  Result struct { ID string `json:"id"` } `json:"result"`
}

type ErrorResponse struct {
  Result  string `json:"result"`
  Message string `json:"message"`
}

func sendEmail() error {
  apiKey := "your-api-key-here"
  baseURL := "https://pub-api.mailenv.com"

  payload := MailData{To: "recipient@example.com", From: "sender@example.com", Subject: "Test Email", Message: "This is a test email message"}
  data, _ := json.Marshal(payload)

  req, err := http.NewRequest("POST", baseURL+"/api/v1/send-mail", bytes.NewBuffer(data))
  if err != nil { return err }
  req.Header.Set("Authorization", apiKey)
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { return err }
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)

  if resp.StatusCode == 201 {
    var ok ApiResponse
    json.Unmarshal(body, &ok)
    fmt.Println("✅ Email sent successfully! ID:", ok.Result.ID)
  } else {
    var er ErrorResponse
    json.Unmarshal(body, &er)
    fmt.Println("❌ Error:", er.Message)
  }
  return nil
}

func main(){ _ = sendEmail() }

PHP — cURL

<?php
$apiKey = 'your-api-key-here';
$baseUrl = 'https://pub-api.mailenv.com';
$mailData = [ 'to' => 'recipient@example.com', 'from' => 'sender@example.com', 'subject' => 'Test Email', 'message' => 'This is a test email message' ];
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => $baseUrl . '/api/v1/send-mail',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($mailData),
  CURLOPT_HTTPHEADER => [ 'Authorization: ' . $apiKey, 'Content-Type: application/json' ]
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) { $result = json_decode($response, true); echo "✅ Email sent successfully! ID: " . $result['result']['id']; }
else { $error = json_decode($response, true); echo "❌ Error: " . $error['message']; }
?>

Ruby — net/http

require 'net/http'
require 'json'
require 'uri'

api_key = 'your-api-key-here'
base_url = 'https://pub-api.mailenv.com'

mail_data = { to: 'recipient@example.com', from: 'sender@example.com', subject: 'Test Email', message: 'This is a test email message' }

uri = URI("#{base_url}/api/v1/send-mail")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req['Authorization'] = api_key
req['Content-Type'] = 'application/json'
req.body = mail_data.to_json

res = http.request(req)
if res.code == '201'
  result = JSON.parse(res.body)
  puts "✅ Email sent successfully! ID: #{result['result']['id']}"
else
  error = JSON.parse(res.body)
  puts "❌ Error: #{error['message']}"
end

cURL

curl -X POST "https://pub-api.mailenv.com/api/v1/send-mail" \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "from": "sender@example.com",
    "subject": "Test Email",
    "message": "This is a test email message"
  }'

Support

For API support or questions, please contact the development team.