1. Help Center
  2. Technical questions

Using the API for the Seed List

The Warmy Seed List API allows you to programmatically manage your email warm-up Seed Lists, including retrieving data, managing approved senders, and downloading Seed Lists. 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.

Authentication via API_KEY

All API requests must include API_KEY for authentication.

 Add the following headers to your requests:

  • Authorization: Bearer your_token ( your_token = API_KEY)
    (For example: Bearer hA7pK2JzX3B8Vq3TtL9sFZrQb1PyM0XyV9w4MkNh7fYuG0Wb6Rd7GqTkV5L0y9P8)

  • holder-uid: a66a9a755fe16f24fcb99dc8b5f25a50

Generating API_KEY

You can generate your API_KEY directly in your account on https://www.warmy.io.

1. Retrieve Seed Lists

/api/v2/users_splits 

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)

Parameters:

  • filter[group_name] (filter by group name - Seed List tier) - can be: standard | premium
  • filter[provider] (filter by provider) - can be: Gmail | Outlook | Yahoo

Example of response (JSON):

{
  "users_splits": [
    {
      "id": 0,
      "last_download": "string",
      "seeds_amount": 0,
      "possible_senders_amount": 0,
      "added_senders_amount": 0,
      "provider": "string",
      "last_updated": "string",
      "expired_at": "string",
      "group_name": "string",
      "refreshed_split": true,
      "next_rotation": "string"
    }
  ]
}

2. Get Specific Seed List

/api/v2/users_splits/{id} 

GET 

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)

Parameters:

  • id * required (user split id)

Example of response (JSON):

{
  "id": 0,
  "last_download": "string",
  "seeds_amount": 0,
  "possible_senders_amount": 0,
  "added_senders_amount": 0,
  "provider": "string",
  "last_updated": "string",
  "expired_at": "string",
  "group_name": "string",
  "refreshed_split": true,
  "next_rotation": "string",
  "senders_list": [
    {
      "id": 0,
      "email": "string",
      "domain": "string"
    }
  ]
}

3. Update Seed List

/api/v2/users_splits/{id} 

PUT

Description:

In the _destroy field, set to true to remove a seed email.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)

Parameters:

  • id * required (user split id)

Example of a request body (JSON):

To add a sender email, use the following format:

{
  "users_split": {
    "users_splits_senders_attributes": [
      {
        "id": 0,
        "email": "string",
      "_destroy": false
      }
    ]
  }
}
To delete a sender email, use the following format:
{
  "users_split": {
    "users_splits_senders_attributes": [
      {
        "id": 0,
        "email": "string",
        "_destroy": true
      }
    ]
  }
}

4. Retrieve Seed List emails

/api/v2/users_splits/{id}/seedlist_emails

GET

Description:

Use 5000 in the per_page parameter to fetch large Seed Lists.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)

Parameters:

  • page (page number (default: 1))
  • per_page (page number, default: 2000, max: 5000)

Example of response (JSON):

{
  "items": [
    "string"
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 0,
    "prev_page": 0,
    "next_page": 0,
    "limit_value": true,
    "first_page?": true,
    "last_page?": true,
    "out_of_range?": true
  }
}

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 Seed List data into your email workflows.