Documentation API Reference Examples Support
Dashboard Sign Up

Codmail API Documentation

Developer First · Simple RESTful API · 99.99% Uptime

The Codmail Email API enables developers to integrate transactional emails, marketing campaigns, and automated communications into their applications. Clean, well-documented API with client libraries in all major languages. Get started in minutes.

Base API URL: https://api.codmail.com/v1/
All endpoints use JSON payloads and require authentication via API key.

Quick Example

Send an email 
POST https://api.codmail.com/v1/send
{
  "api_key": "cod_p_699ed40a_c4ca42_568728f176329d93",
  "to": "user@example.com",
  "subject": "Welcome to Codmail",
  "html": "<h1>Hello!</h1><p>Thanks for signing up.</p>",
  "from": "notifications@yourdomain.com"
}
PHP
Python
Node.js
Java
Ruby
Go
Swift
JavaScript
Rust
Kotlin
C#
more

API Keys

Authenticate your API requests using your API keys. You can generate and manage API keys from your dashboard under the API Keys section.

Your API Keys

These keys are displayed only once after generation. Store them securely.

Production API Key (live)
cod_p_699ed40a_c4ca42_568728f176329d93
Test API Key (sandbox)
cod_t_699ed40a_c4ca42_568728f176329d93

Keys follow the format: cod_p_xxxxxxxx_xxxxxxxx_xxxxxxxxxxxxxxxxxxxx (production) or cod_t_xxxxxxxx_xxxxxxxx_xxxxxxxxxxxxxxxxxxxx (test)

Generate New API Key

To generate a new API key:

  1. Log in to your Codmail Dashboard
  2. Navigate to Settings → API Keys
  3. Click "Generate New Key"
  4. Choose environment (Test/Production) and set permissions
  5. Copy and store the key immediately
Security Note: Never expose your API keys in client-side code or public repositories. Use environment variables on your server.

Webhooks

Configure webhooks to receive real-time updates about email delivery events (delivered, opened, clicked, bounced, etc.).

Webhook Configuration

Set up your webhook endpoint in the dashboard to receive event notifications.

Your Webhook URL (configured in dashboard)
https://your-app.com/codmail-webhook.php

Your endpoint must return HTTP 200 OK to acknowledge receipt.

Webhook Events

Event Type Description Payload Example
email.delivered Email successfully delivered to recipient's server {"event":"delivered","email_id":"msg_123","timestamp":"2025-02-25T10:30:00Z"}
email.opened Recipient opened the email (tracking pixel) {"event":"opened","email_id":"msg_123","ip":"192.168.1.1"}
email.clicked Recipient clicked a link in the email {"event":"clicked","email_id":"msg_123","url":"https://..."}
email.bounced Email bounced (permanent or temporary) {"event":"bounced","email_id":"msg_123","reason":"invalid mailbox"}

Sample Webhook Handler (PHP)

webhook.php 
// webhook.php - Receive Codmail webhook events
<?php
$raw_data = file_get_contents('php://input');
$event = json_decode($raw_data, true);

// Log the event (for debugging)
error_log('Codmail webhook: ' . print_r($event, true));

// Process based on event type
if ($event['event'] === 'delivered') {
    // Update delivery status in database
    $email_id = $event['email_id'];
    // ... your logic
} elseif ($event['event'] === 'opened') {
    // Track opens
    $email_id = $event['email_id'];
    // ... your logic
} elseif ($event['event'] === 'bounced') {
    // Handle bounced email
    $email_id = $event['email_id'];
    $reason = $event['reason'];
    // ... mark as bounced
}

// IMPORTANT: Return 200 to acknowledge receipt
http_response_code(200);
echo 'OK';
?>
To configure webhooks: Go to Dashboard → Webhooks, add your endpoint URL, and select which events to receive. Test with our Send Test Webhook button.

Send Email

Send a single transactional or marketing email.

Endpoint

POST https://api.codmail.com/v1/send

Request Parameters

Parameter Type Required Description
api_key string Yes Your Codmail API key
to string or array Yes Recipient email address(es). Single string or array for multiple.
subject string Yes Email subject line
html string Yes* HTML content of the email (required if text not provided)
text string Yes* Plain text content (required if html not provided)
from string No Sender email (defaults to your verified domain)
from_name string No Sender name (e.g., "Codmail Team")
reply_to string No Reply-to email address
attachments array No Array of file attachments (see Attachments section)
headers object No Custom email headers (e.g., X-Custom-Header)

Example Request (PHP)

send-email.php 
// send-email.php
<?php
$api_key = 'cod_p_699ed40a_c4ca42_568728f176329d93';
$url = 'https://api.codmail.com/v1/send';

$data = [
    'api_key' => $api_key,
    'to' => 'user@example.com',
    'subject' => 'Welcome to Codmail',
    'html' => '<h1>Hello!</h1><p>Thanks for joining.</p>',
    'text' => 'Hello! Thanks for joining.',
    'from' => 'notifications@yourdomain.com',
    'from_name' => 'Codmail Team'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 200) {
    $result = json_decode($response, true);
    echo 'Email sent! Message ID: ' . $result['message_id'];
} else {
    echo 'Error: ' . $response;
}
?>

Example Request (JavaScript)

send-email.js 
const apiKey = 'cod_p_699ed40a_c4ca42_568728f176329d93';

const response = await fetch('https://api.codmail.com/v1/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: apiKey,
    to: 'user@example.com',
    subject: 'Welcome to Codmail',
    html: '<h1>Hello!</h1><p>Thanks for joining.</p>',
    from: 'notifications@yourdomain.com'
  })
});

const data = await response.json();
if (response.ok) {
  console.log('Email sent! ID:', data.message_id);
} else {
  console.error('Error:', data.error);
}

Response

{
  "success": true,
  "message_id": "msg_1234567890abcdef",
  "status": "queued",
  "timestamp": "2025-02-25T10:30:00Z"
}
Copied!