The Warmforge API allows you to programmatically manage mailboxes, monitor warmup performance, and run inbox placement tests without using the Warmforge user interface. This makes it easier to integrate Warmforge into your own systems, automate mailbox management, and build custom reporting workflows.
All API requests are made against:
https://api.warmforge.ai/public/v1
The API uses HTTPS and requires authentication before requests can be made.
Customers typically use the Warmforge API to:
Add and connect mailboxes at scale
Update mailbox settings in bulk
Retrieve mailbox health and warmup statistics
Monitor inbox placement performance
Create and manage placement tests
Build internal dashboards and reporting tools
Automate onboarding and mailbox provisioning
Before using the API, you'll need to authorize your requests using your Warmforge API credentials.
Once authenticated, you can interact with resources within your workspace by providing the appropriate workspaceID in your requests.
Example endpoint structure:
/workspaces/{workspaceID}/mailboxes
Mailbox endpoints allow you to manage warmup mailboxes and retrieve mailbox-related data.
Retrieve all mailboxes within a workspace.
GET /workspaces/{workspaceID}/mailboxes
Common use cases:
Building mailbox inventories
Auditing mailbox status
Syncing mailbox data into external systems
Retrieve details for a specific mailbox.
GET /workspaces/{workspaceID}/mailboxes/{address}
Returns mailbox information including status, provider details, DNS health, and warmup configuration.
Connect a mailbox using OAuth authentication.
POST /workspaces/{workspaceID}/mailboxes/connect-oauth2
Best for providers that support OAuth authentication such as Google Workspace and Microsoft 365.
Connect a mailbox using SMTP credentials.
POST /workspaces/{workspaceID}/mailboxes/connect-smtp
Useful for custom mail servers and providers that do not support OAuth.
Modify mailbox settings.
PATCH /workspaces/{workspaceID}/mailboxes/{address}
Examples include:
Updating warmup limits
Adjusting mailbox configuration
Managing mailbox status
Update multiple mailboxes simultaneously.
POST /workspaces/{workspaceID}/mailboxes/bulk-update
This endpoint is particularly useful for agencies and teams managing large mailbox fleets.
Remove a mailbox from Warmforge.
DELETE /workspaces/{workspaceID}/mailboxes/{address}
Deleting a mailbox stops warmup activity and removes it from your workspace.
View warmup performance metrics for a mailbox.
GET /workspaces/{workspaceID}/mailboxes/{address}/warmup/stats
Statistics may include:
Emails sent
Emails received
Reply activity
Warmup progress
Provider-specific performance data
These metrics can help evaluate mailbox reputation growth over time.
Retrieve the latest inbox placement test results for one or more mailboxes.
POST /workspaces/{workspaceID}/mailboxes/placement-results/latest
This endpoint helps monitor whether emails are landing in:
Primary inboxes
Promotions tabs
Spam folders
Other mailbox categories
Placement tests help measure email deliverability across different mailbox providers.
Retrieve a list of placement tests.
GET /workspaces/{workspaceID}/placement-tests
Useful for reviewing historical deliverability performance.
Create a new inbox placement test.
POST /workspaces/{workspaceID}/placement-tests
A placement test sends messages to a predefined testing network and measures where they land.
Common use cases:
Pre-launch deliverability checks
Monitoring mailbox health
Comparing sending infrastructure performance
Retrieve details and results for a specific placement test.
GET /workspaces/{workspaceID}/placement-tests/{placementTestID}
Results can help identify:
Inbox placement rates
Spam folder placement
Provider-specific deliverability issues
Remove a placement test.
DELETE /workspaces/{workspaceID}/placement-tests/{placementTestID}
The API exposes several response models that provide detailed mailbox and deliverability information, including:
Mailbox status
Provider information
DNS configuration
Health checks
Blacklist monitoring
Warmup statistics
Placement test configuration
Test targets
Deliverability results
Inbox placement rates
SPF status
DKIM status
DNS records
Blacklist checks
Overall mailbox health
A common API workflow looks like this:
Connect a mailbox using OAuth2 or SMTP.
Verify mailbox health and DNS configuration.
Start warmup activity.
Monitor warmup statistics.
Run periodic placement tests.
Track inbox placement results over time.
Update mailbox settings as reputation improves.
The Warmforge API is ideal for:
Agencies managing multiple client mailboxes
Sales teams automating mailbox provisioning
Internal tooling and dashboards
Deliverability monitoring platforms
Large-scale mailbox management workflows
If you only manage a small number of mailboxes, the Warmforge UI may be sufficient. The API becomes especially valuable when you need automation, integrations, or custom reporting