ColdMail API Code Examples

API version: v1

Status: Live

Endpoint: POST https://www.coldmailcalculator.com/api/v1/coldmail/roi

Authentication: x-api-key: YOUR_API_KEY

Content-Type: application/json

Developer preview access includes 100 forecast credits for testing. See Request API Access, API pricing or API overview.

Test the API from your terminal:

curl -X POST https://www.coldmailcalculator.com/api/v1/coldmail/roi \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "emails_sent": 5000,
    "reply_rate": 5,
    "positive_reply_rate": 30,
    "booking_rate": 20,
    "close_rate": 25,
    "average_deal_value": 2500,
    "monthly_tool_cost": 99,
    "sending_infrastructure_cost": 50
  }'

async function forecastCampaign() {
  const response = await fetch(
    "https://www.coldmailcalculator.com/api/v1/coldmail/roi",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.COLDMAIL_API_KEY
      },
      body: JSON.stringify({
        emails_sent: 5000,
        reply_rate: 5,
        positive_reply_rate: 30,
        booking_rate: 20,
        close_rate: 25,
        average_deal_value: 2500,
        monthly_tool_cost: 99,
        sending_infrastructure_cost: 50
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || "API error");
  }

  const data = await response.json();
  return data;
}

// Usage
forecastCampaign().then(data => {
  console.log("Estimated replies:", data.estimated_replies);
  console.log("Positive replies:", data.positive_replies);
  console.log("Booked calls:", data.booked_calls);
  console.log("Estimated clients:", data.estimated_clients);
  console.log("Estimated revenue:", data.estimated_revenue);
  console.log("Estimated profit:", data.estimated_profit);
  console.log("Campaign score:", data.campaign_score);
  console.log("Risk level:", data.risk_level);
});

Call the ColdMail API from Python:

import requests

url = "https://www.coldmailcalculator.com/api/v1/coldmail/roi"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}
payload = {
    "emails_sent": 5000,
    "reply_rate": 5,
    "positive_reply_rate": 30,
    "booking_rate": 20,
    "close_rate": 25,
    "average_deal_value": 2500,
    "monthly_tool_cost": 99,
    "sending_infrastructure_cost": 50
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(f"Estimated replies: {data['estimated_replies']}")
print(f"Positive replies: {data['positive_replies']}")
print(f"Booked calls: {data['booked_calls']}")
print(f"Estimated clients: {data['estimated_clients']}")
print(f"Estimated revenue: ${data['estimated_revenue']}")
print(f"Estimated profit: ${data['estimated_profit']}")
print(f"Campaign score: {data['campaign_score']}")
print(f"Risk level: {data['risk_level']}")

Parse the API response and extract key metrics for your UI:

// Sample API response
// Recommendations are rules-based forecasting intelligence,
// derived from input-sensitive scenario comparison logic.
const forecast = {
  "estimated_replies": 250,
  "positive_replies": 75,
  "booked_calls": 15,
  "estimated_clients": 4,
  "estimated_revenue": 10000,
  "estimated_profit": 9851,
  "campaign_score": "Strong",
  "risk_level": "Moderate",
  "recommendations": [
    "Your positive reply rate is low relative to total replies. Consider tighter targeting and message-market fit before increasing volume.",
    "Booking rate is reasonable but close rate could widen your funnel. Review post-call conversion process for improvement opportunities."
  ]
};

// Display in a dashboard widget
function renderForecast(forecast) {
  return {
    summary: `${forecast.estimated_clients} clients from ${forecast.booked_calls} booked calls`,
    revenue: `$${forecast.estimated_revenue.toLocaleString()}`,
    profit: `$${forecast.estimated_profit.toLocaleString()}`,
    score: forecast.campaign_score,
    risk: forecast.risk_level,
    tips: forecast.recommendations
  };
}

Always handle API errors in your integration. The API returns nested error objects:

try {
  const response = await fetch(
    "https://www.coldmailcalculator.com/api/v1/coldmail/roi",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
      },
      body: JSON.stringify(payload)
    }
  );

  if (response.status === 401) {
    showError("Invalid API key. Check your x-api-key value or create a free key.");
    return;
  }

  if (response.status === 400) {
    const errorData = await response.json();
    const message = errorData.error?.message || "Invalid request.";
    showError(message);
    return;
  }

  if (response.status === 405) {
    showError("Invalid request method. Use POST for this endpoint.");
    return;
  }

  if (!response.ok) {
    const errorData = await response.json();
    const message = errorData.error?.message || "API error. Please try again.";
    showError(message);
    return;
  }

  const data = await response.json();
  displayForecast(data);

} catch (error) {
  showError("Network error. Check your connection.");
}