MailEnv Public API

API reference

A managed REST API wrapper for Amazon SES, with API key authentication. JSON in, JSON out. Everything you need to send transactional email from your own code.

OpenAPI 3.1 spec Quick start

Introduction

The MailEnv Public API sends email over HTTPS. Every endpoint requires a valid API key in the Authorization header, accepts a JSON body, and returns JSON.

Base URL: https://pub-api.mailenv.com
Auth: API key in the Authorization header
Format: application/json

Base URL

https://pub-api.mailenv.com

Authentication

Authenticate every request with your API key in the Authorization header. Requests without a valid, active key return 401.

Keep keys out of client-side code and version control. Load them from an environment variable or a secrets manager.

Authorization: your-api-key-here

Errors

MailEnv uses standard HTTP status codes. Errors return a JSON body with "result": "error" and a human-readable message.

Status	Meaning	When it happens
201	Created	The mail request was accepted.
400	Bad Request	Validation failed: a required field is missing or the JSON is invalid.
401	Unauthorized	The API key is invalid, or the account is locked.
403	Forbidden	Invalid tokens, or your email volume has expired.
429	Too Many Requests	You hit the throttling limit. Back off and retry.
500	Internal Server Error	Something went wrong on our side. Retry with backoff.

Send mail

POST /api/v1/send-mail

Sends an email message using the provided parameters. Requires authentication.

Headers

Authorizationstringrequired
Your API key.
Content-Typestringrequired
Must be application/json.

Body parameters

tostringrequired
Recipient email address.
fromstringrequired
Sender email address.
subjectstringrequired
Email subject line.
messagestringrequired
Email message body.

Response

result.idstringrequired
Unique identifier for the mail request (UUID).

Notes

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

Request

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"
  }'

Response

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

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

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

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

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

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

Code examples

Complete, copy-paste examples for POST /api/v1/send-mail. Replace your-api-key-here with your key.

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"
  }'

import requests

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

response = requests.post(
    f"{BASE_URL}/api/v1/send-mail",
    headers={
        "Authorization": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "to": "recipient@example.com",
        "from": "sender@example.com",
        "subject": "Test Email",
        "message": "This is a test email message",
    },
)

if response.status_code == 201:
    print("Sent:", response.json()["result"]["id"])
else:
    print("Error:", response.json()["message"])

import asyncio
import httpx

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

async def send_email():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{BASE_URL}/api/v1/send-mail",
            headers={
                "Authorization": API_KEY,
                "Content-Type": "application/json",
            },
            json={
                "to": "recipient@example.com",
                "from": "sender@example.com",
                "subject": "Test Email",
                "message": "This is a test email message",
            },
        )

    if response.status_code == 201:
        print("Sent:", response.json()["result"]["id"])
    else:
        print("Error:", response.json()["message"])

asyncio.run(send_email())

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

const res = await fetch(`${BASE_URL}/api/v1/send-mail`, {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'recipient@example.com',
    from: 'sender@example.com',
    subject: 'Test Email',
    message: 'This is a test email message',
  }),
});

const data = await res.json();
if (res.status === 201) console.log('Sent:', data.result.id);
else console.error('Error:', data.message);

import axios from 'axios';

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

try {
  const res = await axios.post(
    `${BASE_URL}/api/v1/send-mail`,
    {
      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' } }
  );
  console.log('Sent:', res.data.result.id);
} catch (error) {
  console.error('Error:', error.response?.data?.message ?? error.message);
}

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"`
}

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

	req, _ := http.NewRequest("POST", "https://pub-api.mailenv.com/api/v1/send-mail", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "your-api-key-here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

<?php
$ch = curl_init('https://pub-api.mailenv.com/api/v1/send-mail');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: your-api-key-here',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => 'recipient@example.com',
    'from' => 'sender@example.com',
    'subject' => 'Test Email',
    'message' => 'This is a test email message',
  ]),
]);

$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status === 201
  ? 'Sent: ' . $response['result']['id']
  : 'Error: ' . $response['message'];

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

uri = URI('https://pub-api.mailenv.com/api/v1/send-mail')

req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'your-api-key-here'
req['Content-Type'] = 'application/json'
req.body = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  message: 'This is a test email message'
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

puts res.code == '201' ? "Sent: #{data['result']['id']}" : "Error: #{data['message']}"

Need help with the API?

Questions, migrations, or something not working the way you expect: talk to the team that builds it.

Contact support Email us