1. Overview

The ColdMailCalculator API lets you forecast cold email campaign ROI programmatically. Send campaign parameters — volume, reply rates, booking rates, deal value, costs — and receive back estimated positive replies, booked calls, revenue, profit, a campaign score, and risk level.

Base endpoint:
https://www.coldmailcalculator.com/api/v1/coldmail/roi

2. Authentication

All API requests require an API key passed via the x-api-key header.

x-api-key: YOUR_API_KEY

To request API access, request API access — reviewed within 1 business day.

3. Free API Access

100 credits included — use them when you need forecasts. No credit card required.

The Free plan includes 100 credits — enough to forecast several campaigns, test assumptions, and build a prototype. Buy credit packs when you need more.

4. ROI Forecast Endpoint

POST /api/v1/coldmail/roi

Returns a forecast based on your campaign parameters. All fields are required unless marked optional.

5. Request Fields

Field	Type	Description
emails_sent	integer	Total number of emails sent in the campaign required
delivery_rate	float (0–1)	Fraction of emails that reached the inbox required
reply_rate	float (0–1)	Fraction of delivered emails that got any reply required
positive_reply_rate	float (0–1)	Fraction of replies that are positive/ interested required
booking_rate	float (0–1)	Fraction of positive replies that book a call required
close_rate	float (0–1)	Fraction of booked calls that close into a customer required
average_deal_value	float	Average revenue per closed deal in USD required
monthly_tool_cost	float	Monthly cost of your tools/software in USD required
sending_infrastructure_cost	float	Monthly cost of email infrastructure in USD required

6. Response Fields

Field	Type	Description
positive_replies	integer	Estimated number of positive/ interested replies
booked_calls	integer	Estimated number of booked calls
estimated_revenue	float	Estimated total revenue in USD
estimated_profit	float	Estimated profit after costs in USD
campaign_score	float (0–100)	Overall campaign health score
risk_level	string	Risk assessment: low, medium, or high

7. Example cURL Request

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": 1000,
    "delivery_rate": 0.9,
    "reply_rate": 0.05,
    "positive_reply_rate": 0.3,
    "booking_rate": 0.4,
    "close_rate": 0.2,
    "average_deal_value": 3000,
    "monthly_tool_cost": 99,
    "sending_infrastructure_cost": 50
  }'

8. JavaScript Example

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({
      emails_sent: 1000,
      delivery_rate: 0.9,
      reply_rate: 0.05,
      positive_reply_rate: 0.3,
      booking_rate: 0.4,
      close_rate: 0.2,
      average_deal_value: 3000,
      monthly_tool_cost: 99,
      sending_infrastructure_cost: 50
    })
  }
);

const data = await response.json();
console.log(data);
/* {
  "positive_replies": 13,
  "booked_calls": 5,
  "estimated_revenue": 3000,
  "estimated_profit": 2851,
  "campaign_score": 68,
  "risk_level": "medium"
} */

9. Python Example

import requests

response = requests.post(
    "https://www.coldmailcalculator.com/api/v1/coldmail/roi",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "emails_sent": 1000,
        "delivery_rate": 0.9,
        "reply_rate": 0.05,
        "positive_reply_rate": 0.3,
        "booking_rate": 0.4,
        "close_rate": 0.2,
        "average_deal_value": 3000,
        "monthly_tool_cost": 99,
        "sending_infrastructure_cost": 50
    }
)

data = response.json()
print(data)
# {
#   "positive_replies": 13,
#   "booked_calls": 5,
#   "estimated_revenue": 3000,
#   "estimated_profit": 2851,
#   "campaign_score": 68,
#   "risk_level": "medium"
# }

10. Error Handling

The API returns standard HTTP status codes:

Status Code	Meaning
200	Success — forecast returned
400	Bad request — missing or invalid fields
401	Unauthorized — missing or invalid API key
429	Rate limit exceeded — upgrade your plan for more calls
500	Internal server error — try again later

Error responses include a JSON body with a message field describing the issue.

11. Pricing & Limits

Plan	Price	Credits
Free	$0 USD	100 credits
Starter Pack	$29 USD	1,000 credits
Growth Pack	$79 USD	5,000 credits
Scale Pack	$199 USD	20,000 credits
Enterprise	Custom	Custom

Free tier includes 100 credits. Buy credit packs when you need more. No credit card required.

View full pricing →

ColdMailCalculator Docs