Integrate Email Warmer into your applications with our comprehensive REST API. Manage mailboxes, monitor warming progress, and test deliverability programmatically.
The Email Warmer API is a RESTful API that allows you to programmatically manage your email warmup campaigns, test deliverability, and monitor performance. All API requests are made over HTTPS and responses are returned in JSON format.
https://api.emailwarmer.io/v1
API requests are rate limited to 1000 requests per hour per API key. Rate limit headers are included in all responses:
X-RateLimit-Limit - Maximum requests per hourX-RateLimit-Remaining - Remaining requests in current windowX-RateLimit-Reset - Time when the rate limit resetsAll API requests require authentication using your API key. Include your API key in the Authorization header of every request.
Include your API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.emailwarmer.io/v1/mailboxesRetrieve a list of all mailboxes in your account.
/mailboxes
{
"data": [
{
"id": "mb_1234567890",
"email": "[email protected]",
"provider": "gmail",
"status": "active",
"reputation_score": 94.2,
"daily_volume": 50,
"created_at": "2025-09-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1
}
}Add a new mailbox to your account for warming.
/mailboxes
{
"email": "[email protected]",
"provider": "gmail",
"daily_volume": 50,
"credentials": {
"access_token": "ya29.a0AfH6SMC...",
"refresh_token": "1//04..."
}
}{
"data": {
"id": "mb_1234567890",
"email": "[email protected]",
"provider": "gmail",
"status": "pending_verification",
"reputation_score": null,
"daily_volume": 50,
"created_at": "2025-09-15T10:30:00Z"
}
}Retrieve detailed information about a specific mailbox.
/mailboxes/{id}
{
"data": {
"id": "mb_1234567890",
"email": "[email protected]",
"provider": "gmail",
"status": "active",
"reputation_score": 94.2,
"daily_volume": 50,
"emails_sent_today": 23,
"inbox_placement_rate": 89.3,
"spam_rate": 2.1,
"created_at": "2025-09-15T10:30:00Z",
"last_activity": "2025-09-15T14:22:00Z"
}
}Initiate a new spam test and get the tracking code and seed list.
/spam-tests
{
"data": {
"id": "st_1234567890",
"tracking_code": "EW12345678",
"seed_list": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"status": "pending",
"created_at": "2025-09-15T10:30:00Z"
}
}Retrieve the detailed results of a completed spam test.
/spam-tests/{id}
{
"data": {
"id": "st_1234567890",
"tracking_code": "EW12345678",
"status": "completed",
"spam_score": 2.5,
"placement_results": {
"inbox": 85,
"spam": 10,
"promotions": 5
},
"analysis": {
"spf_status": "pass",
"dkim_status": "pass",
"dmarc_status": "pass",
"blacklist_status": "clean",
"spam_words": ["urgent", "limited time"],
"broken_links": 0
},
"created_at": "2025-09-15T10:30:00Z",
"completed_at": "2025-09-15T10:35:00Z"
}
}Retrieve analytics data for your mailboxes.
/analytics?mailbox_id={id}&period=7d
mailbox_id - Filter by specific mailbox (optional)period - Time period: 1d, 7d, 30d, 90d (default: 7d)provider - Filter by email provider (optional){
"data": {
"overview": {
"total_mailboxes": 3,
"active_mailboxes": 2,
"avg_reputation_score": 94.2,
"avg_inbox_placement": 89.3,
"total_emails_sent": 1247
},
"daily_stats": [
{
"date": "2025-09-15",
"emails_sent": 156,
"reputation_score": 94.2,
"inbox_placement_rate": 89.3,
"spam_rate": 2.1
}
],
"mailbox_performance": [
{
"mailbox_id": "mb_1234567890",
"email": "[email protected]",
"reputation_score": 96.5,
"inbox_placement_rate": 94.2,
"emails_sent": 487
}
]
}
}Webhooks allow you to receive real-time notifications about events in your Email Warmer account. Configure webhook endpoints to stay updated on mailbox status changes, reputation updates, and more.
mailbox.connected - Mailbox successfully connectedmailbox.paused - Mailbox warming pausedmailbox.resumed - Mailbox warming resumedreputation.updated - Reputation score updatedspam_test.completed - Spam test completed{
"id": "evt_1234567890",
"type": "reputation.updated",
"created": "2025-09-15T10:30:00Z",
"data": {
"mailbox_id": "mb_1234567890",
"email": "[email protected]",
"reputation_score": 94.2,
"previous_score": 92.1
}
}The API uses conventional HTTP response codes to indicate success or failure. All errors return a JSON response with details about what went wrong.
{
"error": {
"code": "invalid_request",
"message": "The request was invalid",
"details": {
"field": "email",
"reason": "Invalid email format"
}
}
}| Code | Status | Description |
|---|---|---|
| invalid_request | 400 | The request was invalid or malformed |
| unauthorized | 401 | Invalid or missing API key |
| forbidden | 403 | Insufficient permissions |
| not_found | 404 | Resource not found |
| rate_limited | 429 | Rate limit exceeded |
Get started quickly with our official SDKs and community libraries
Start building with our API and improve your email deliverability programmatically.