The Warmy Seedlist API allows you to programmatically manage your email warm-up seed lists, including retrieving data, managing approved senders, and downloading seedlists. Below is a step-by-step guide to using the API’s key features.
{
"users_split": {
"users_splits_senders_attributes": [
{
"id": 456,
"email": "new_seed@domain.com",
"_destroy": false
}
]
}
}
Using Warmy with an API
Warmy provides an API that allows you to manage your Seed list programmatically. This can be useful for automating tasks or integrating Warmy with other applications.
Prerequisites
Before you can use the API, you need to already be registered on warmy.io
Server
The Warmy API is available at https://api.warmy.io.
Important Update: Transition from "Sign in" to API_KEY
The sign_in
method is deprecated and will be disabled starting June 10.
Please switch to using API_KEY for authentication.
What You Need to Do:
- For generating your API_KEY, contact Customer Success or Support.
- Use API_KEY in your API requests moving forward.
How to Use API_KEY:
-
Add the following headers to all API V2 requests:
-
Authorization:
Bearer your_token
( your_token = API_KEY) -
holder-uid: a66a9a755fe16f24fcb99dc8b5f25a50
-
❗Important:
-
Do not use the following parameters if you are using API_KEY:
-
client
-
access-token
-
uid
-
Sign in
❗You will receive access-token, uid, and client in response headers
Include these headers in all subsequent API requests
POST
Headers:
holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)
Example of a request body (JSON):
{
"email": "string",
"password": "string"
}
1. Retrieve Seed Lists
/api/v2/users_splits
GET
Headers
Parameter | Type | Required | Description |
---|---|---|---|
client |
string | Yes | Client identifier |
access-token |
string | Yes | Authentication token |
uid |
string | Yes | User UID |
holder-uid |
string | Yes | Holder UID (a66a9a755fe16f24fcb99dc8b5f25a50 ) |
Query Parameters
Parameter | Values | Description |
---|---|---|
filter[group_name] |
standard | premium |
Filter by Seed List tier |
filter[provider] |
Gmail | Outlook | Yahoo |
Filter by email provider |
Example Response:
{
"users_splits": [
{
"id": 123,
"last_download": "2025-03-25",
"seeds_amount": 500,
"possible_senders_amount": 1000,
"provider": "Gmail",
"group_name": "premium"
}
]
}
2. Get Specific Seed List
GET
Headers
Parameter | Type | Required | Description |
---|---|---|---|
client |
string | Yes | Client identifier |
access-token |
string | Yes | Authentication token |
uid |
string | Yes | User UID |
holder-uid |
string | Yes | Holder UID (a66a9a755fe16f24fcb99dc8b5f25a50 ) |
Path Parameter
Parameter | Type | Description |
---|---|---|
id |
integer | Seed List ID |
Example Response:
{
"id": 123,
"senders_list": [
{
"id": 456,
"email": "seed1@domain.com",
"domain": "domain.com"
}
],
"seeds_amount": 500
}
3. Update Seed List
PUT
Headers
Parameter | Type | Required | Example |
---|---|---|---|
client |
string | Yes | client: your-client-key |
access-token |
string | Yes | access-token: abc123xyz |
uid |
string | Yes | uid: user-123 |
holder-uid |
string | Yes | holder-uid: a66a9a755fe16f24fcb99dc8b5f25a50 |
Content-Type |
string | Yes | Content-Type: application/json |
Path Parameter
Parameter | Type | Description |
---|---|---|
id |
integer | Seed List ID |
Request Body
To add a sender email, use the following format:
{
"users_split": {
"users_splits_senders_attributes": [
{
"id": 456,
"email": "new_seed@domain.com",
"_destroy": false
}
]
}
}
{
"users_split": {
"users_splits_senders_attributes": [
{
"id": 456,
"email": "new_seed@domain.com",
"_destroy": true
}
]
}
}
4. Retrieve Seed List Emails
GET
Headers
Parameter | Type | Required | Example |
---|---|---|---|
client |
string | Yes | client: your-client-key |
access-token |
string | Yes | access-token: abc123xyz |
uid |
string | Yes | uid: user-123 |
holder-uid |
string | Yes | holder-uid: a66a9a755fe16f24fcb99dc8b5f25a50 |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Items per page (max 5000) |
Response:
{
"items": ["seed1@domain.com", "seed2@domain.com"],
"pagination": {
"current_page": 2,
"total_pages": 5
}
}
Key Parameters
Field | Usage |
---|---|
_destroy |
Set to true to remove a seed email |
per_page |
Use 5000 to fetch large Seed Lists |
filter[provider] |
Segment Seed Lists by ESP |
Need help? Contact hi@warmy.io
Why Use the API?
-
Automation: Manage splits and senders programmatically.
-
Scalability: Handle large volumes of splits and seeds efficiently.
-
Integration: Seamlessly integrate seedlist data into your email workflows.