Overview
The first ColdMail API endpoint turns cold email campaign assumptions into a deterministic forecast. It is built for AI sales tools, outbound dashboards, agency reporting, CRM copilots, and sales audit tools.
ColdMail API does not send email, scrape leads, or guarantee campaign outcomes.
Authentication
Send your API key in the x-api-key header:
x-api-key: YOUR_API_KEY
API keys are generated instantly at /api/get-key/. Keys are delivered to your email after confirmation.
Endpoint
Base URL
https://www.coldmailcalculator.com/api
Endpoint
POST /v1/coldmail/roi
Full URL
https://www.coldmailcalculator.com/api/v1/coldmail/roi
Status
● Live
Headers
Content-Type: application/json x-api-key: YOUR_API_KEY
The endpoint also responds to OPTIONS preflight requests with CORS headers for browser-based integrations.
Request body
Rates are entered as percentages, not decimals. Example: 5 means 5%, not 0.05.
Required fields: emails_sent, reply_rate, positive_reply_rate, booking_rate, close_rate, average_deal_value
Optional fields: monthly_tool_cost, sending_infrastructure_cost
| Field | Type | Rules |
|---|---|---|
| emails_sent | number | Required integer, minimum 1. |
| reply_rate | number | Required percent from 0 to 100. |
| positive_reply_rate | number | Required percent from 0 to 100. |
| booking_rate | number | Required percent from 0 to 100. |
| close_rate | number | Required percent from 0 to 100. |
| average_deal_value | number | Required, minimum 0. |
| monthly_tool_cost | number | Optional, minimum 0. Defaults to 0. |
| sending_infrastructure_cost | number | Optional, minimum 0. Defaults to 0. |
{
"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 body
| Field | Description |
|---|---|
| delivered | Forecasted delivered messages. |
| replies | Forecasted total replies. |
| positive_replies | Forecasted interested or qualified replies. |
| booked_calls | Forecasted meetings booked. |
| closed_deals | Forecasted clients won. |
| revenue | Forecasted revenue from closed deals. |
| profit | Forecasted profit after campaign costs. |
| roi_multiple | Revenue divided by campaign cost. |
| cost_per_meeting | Campaign cost divided by booked calls. |
| performance_grade | Strong, Moderate, or Weak based on expected outcomes. |
{
"delivered": 4500,
"replies": 225,
"positive_replies": 68,
"booked_calls": 14,
"closed_deals": 4,
"revenue": 10000,
"profit": 9400,
"roi_multiple": 15.7,
"cost_per_meeting": 42.86,
"performance_grade": "Strong"
}
Example cURL
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
}'
Example JavaScript fetch
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: 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
})
});
const data = await response.json();
console.log(data);
Error responses
401 Invalid API Key
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key."
}
}
400 Validation Error
{
"error": {
"code": "invalid_request",
"message": "reply_rate must be 100 or less."
}
}
405 Wrong Method
{
"error": {
"code": "invalid_method",
"message": "Use POST for this endpoint."
}
}
Notes and limitations
Forecasts are estimates for planning and product workflows. They should not be treated as guaranteed replies, meetings, clients, revenue, deliverability, or inbox placement.
ColdMail API does not send email, manage inboxes, scrape leads, write messages, or replace compliance review.
Early-access API keys are issued after setup. Rate limiting and quota enforcement will be added before full production release.
Building a sales tool, agency dashboard, or CRM feature?
Use the ColdMail API to forecast cold email outcomes inside your product.