How do I use Warmy with an API?

• Using Warmy with an API
• YAML file
• Server
• Sign in
• Available subscriptions on your account
• Connecting a new mailbox
• Change the settings of mailbox
• Disconnect a mailbox
• Change the state of the mailbox
• Change subscription for the mailbox
• Reconnect the mailbox
• List of mailboxes with statistics 
• Get Warmup deliverability statistics by Mailbox IDs
• Mailbox information - Statistics for a separate mailbox
• Run a deliverability test
  
• Get full info about deliverability checker

• Get a list of deliverability tests
• Run a deliverability auto-test
• Change deliverability auto-test settings of multiple mailboxes
• DNS records test for the mailbox
• DNS records test for all mailboxes

Using Warmy with an API

Warmy provides an API that allows you to manage your account and mailboxes programmatically. This can be useful for automating tasks or integrating Warmy with other applications.

Before you can use the API, you need to already be registered on warmy.io 

YAML file: 

Download

Server

The Warmy API is available at https://api.warmy.io.

Sign in

❗You will receive access-token, uid, and client in response headers

Include these headers in all subsequent API requests

/api/v1/auth/sign_in

Headers:

holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

Example of a request body (JSON):

{
  "email": "string",
  "password": "string"
}

Available subscriptions on your account

/api/v2/tariff_plan_types

Headers:

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

Example of response (JSON):

[
  {
    "id": 0,
    "name": "string"
  }
]

Connecting a new mailbox

/api/v2/mailboxes

Description:

Available providers: Gmail, Outlook, Yahoo, Mailgun, SendGrid, OAuth Google, OAuth Outlook.

• provider
• email
• tariff_plan_type_id 

Field password is required for providers that do not use additional fields starting with smtp_ or imap_.

If field use_imap is true then fields that start with imap_  are required.

The additional_key field is used to access the Mailgun or SendGrid API and detect bounced emails.

Field smtp_user_name for SendGrid should be apikey

Field speed_mode can be as slow, medium, fast.

Headers:

Example of a request body (JSON)

When you connect a mailbox, you will receive the ID parameter of your mailbox, which you will need to use in subsequent operations with that mailbox.

Here you can find example of request body for each provider:

1. Gmail
2. Outlook
3. Yahoo
4. Mailgun
5. SendGrid
6. OAuth Google
7. OAuth Outlook
8. SMTP

Request body for Gmail:

Required fields:

• Email
• password
• provider
• tariff plan id

{
  "mailbox": {
    "email": "string",
    "password": "string",
    "provider": "gmail",
    "from_name": "string",
    "use_imap": boolean,
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for Outlook:

Required fields:

• Email
• password
• provider
• tariff plan id

{
  "mailbox": {
    "email": "string",
    "password": "string",
    "provider": "outlook",
    "from_name": "string",
    "use_imap": boolean,
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for Yahoo:

Required fields:

• Email
• password
• provider
• tariff plan id

{
  "mailbox": {
    "email": "string",
    "password": "string",
    "provider": "yahoo",
    "from_name": "string",
    "use_imap": boolean,
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for Mailgun:

Required fields:

• Email
• provider
• smtp port
• smtp address
• smtp ssl
• smtp user name
• smtp password
• tariff plan id
• If field use_imap is true then fields that start with imap_  are required.

{
  "mailbox": {
    "email": "string",
    "from_name": "string",
    "provider": "mailgun",
    "use_imap": boolean,
    "imap_address": "string",
    "imap_port": integer,
    "imap_ssl": boolean,
    "imap_user_name": "string",
    "imap_password": "string",
    "smtp_port": integer,
    "smtp_address": "string",
    "smtp_ssl": boolean,
    "smtp_user_name": "string",
    "smtp_password": "string",
    "additional_key": "string",
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for SendGrid:

Required fields:

• Email
• provider
• smtp port
• smtp address
• smtp ssl
• smtp user name
• smtp password
• tariff plan id
• If field use_imap is true then fields that start with imap_  are required.

{
  "mailbox": {
    "email": "string",
    "from_name": "string",
    "provider": "sendgrid",
    "use_imap": boolean,
    "imap_address": "string",
    "imap_port": integer,
    "imap_ssl": boolean,
    "imap_user_name": "string",
    "imap_password": "string",
    "smtp_port": integer,
    "smtp_address": "string",
    "smtp_ssl": boolean,
    "smtp_user_name": "apikey",
    "smtp_password": "string",
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for OAuth Google:

This instruction can be used for connecting and reconnecting a mailbox

Authorization scopes

Requires one of the following OAuth scopes:

• https://mail.google.com/
• https://www.googleapis.com/auth/gmail.modify

Required fields:

• Email
• provider
• tariff plan id
• access token
• refresh token
• expires at  -   ( the number of seconds since the Unix Epoch (1970-1-1 00:00:00 UTC))
  
• client id
• client secret   
• redirect uri   
• token credential uri   

{
  "mailbox": {
    "email": "string",
    "from_name": "string",
    "provider": "oauth_google",
    "use_imap": boolean,
    "tariff_plan_type_id": integer,
    "access_token": "string",
    "refresh_token": "string",
    "expires_at": integer,
    "client_id": "string",
    "client_secret": "string",
    "redirect_uri": "string",
    "token_credential_uri": "string",
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for OAuth Outlook:

This instruction can be used for connecting and reconnecting a mailbox

Required fields:

• Email
• provider
• tariff plan id
• access token
• refresh token
• client id
• client secret

{
  "mailbox": {
    "email": "string",
    "from_name": "string",
    "provider": "oauth_outlook",
    "tariff_plan_type_id": integer,
    "access_token": "string",
    "refresh_token": "string",
    "client_id": "string",
    "client_secret": "string",
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Request body for SMTP:

Required fields:

• email
• provider
• use_imap
• smtp port
• smtp address
• smtp ssl
• smtp user name
• smtp password
• tariff plan id
• If field use_imap is true then fields that start with imap_  are required.

{
  "mailbox": {
    "email": "string",
    "from_name": "string",
    "provider": "smtp",
    "use_imap": boolean,
    "imap_address": "string",
    "imap_port": integer,
    "imap_ssl": boolean,
    "imap_user_name": "string",
    "imap_password": "string",
    "smtp_port": integer,
    "smtp_address": "string",
    "smtp_ssl": boolean,
    "smtp_user_name": "string",
    "smtp_password": "string",
    "tariff_plan_type_id": integer,
    "setting_attributes": {
    "speed_mode": "string"
  }
 }
}

Change the settings of mailbox

/api/v2/mailboxes/{id}

Headers:

Parameters:

• id *  (your mailbox number)

Field speed_mode can be as slow, medium, fast.

Example of a request body (JSON):

{
  "mailbox": {
    "from_name": "string",
    "setting_attributes": {
    "speed_mode": "string"

  }
 }
}

Disconnect a mailbox

/api/v2/mailboxes/{id}

Headers:

Parameters:

• id *  (your mailbox number)

Example of a request body (JSON):

{
  "reason": {
    "reason": "string",
    "reason_text": "string"
  }
}

Change the state of the mailbox

/api/v2/mailboxes/{id}/update_state

Headers:

Parameters:

• id *  (your mailbox number)

Example of a request body (JSON):

{
  "mailbox": {
    "state": "activate!"
  }
}

State of mailbox

Enum:

[ activate!, pause! ]

Change subscription for the mailbox

/api/v2/mailboxes/{id}/change_tariff_plan

{
  "mailbox": {
    "tariff_plan_type_id": 0
  }
}

Headers:

Parameters:

• id *  (your mailbox number)

Example of a request body (JSON):

{
  "mailbox": {
    "from_name": "string",
    "password": "string",
    "use_imap": true,
    "imap_address": "string",
    "imap_port": "993",
    "imap_ssl": true,
    "imap_password": "string",
    "imap_user_name": "string",
    "smtp_port": "587",
    "smtp_address": "smtp.mailgun.org",
    "smtp_ssl": true,
    "smtp_password": "string",
    "smtp_user_name": "string",
    "additional_key": "string",
    "tariff_plan_type_id": 0
  }

List of mailboxes with statistics 

/api/v2/mailboxes

Headers:

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

• page  (pagination, in: query)
• filter[email] (filter by email)

Get Warmup deliverability statistics by Mailbox IDs

/api/v2/mailboxes/warmup_statistics

Headers:

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

• filter[time_bucket] (required): Determines the time bucket for statistics. 

• filter[from] (required): The start date for statistics in the format YYYY-MM-DD

• filter[to] (optional): The end date for statistics in the format YYYY-MM-DD. Defaults to the current date if not provided.
• filter[mailbox_ids] (required): A comma-separated list of mailbox IDs to retrieve statistics for.

• The API provides warmup deliverability statistics for specified mailboxes based on the chosen time bucket (hourly, daily or monthly).
• Hourly Statistics:

• Returns hourly statistics for the specified day. The from date must be within the last 7 days from the current date.

• Daily Statistics:

• Returns daily statistics for the specified period. The from date must be within the last 30 days from the current date.

• Monthly Statistics:

• Returns monthly statistics for the specified period. The from date must be older than 30 days from the current date but cannot be earlier than 2024-01-01.

Mailbox information - Statistics for a separate mailbox

/api/v2/mailboxes/{id}

Headers:

Parameters:

• id* (your mailbox number)

Example of response (JSON):

{ 
  "from_name": "string",
  "warmup_active": true,
  "status": "string",
  "deliverability": 0,
  "sent_today": 0,
  "received_today": 0,
  "dns_score": 0,
  "isp_score": 0,
  "created_at": "string",
  "temperature": 0,
  "warmup_language": {
    "name": "string",
    "code": "string"
  },
  "warmup_topic": {
    "id": 0,
    "title": "string"
  },
  "spf": {
    "status": true,
    "title": "string"
  },
  "dkim": {
    "status": true,
    "title": "string"
  },
  "dmarc": {
    "status": true,
    "title": "string"
  },
  "r_dns": {
    "status": true,
    "title": "string"
  },
  "mx_record": {
    "status": true,
    "title": "string"
  },
  "a_record": {
    "status": true,
    "title": "string"
  },
  "latest_deliverability_test": {
    "date": "string",
    "result": {
      "PROVIDER": {
        "inbox": 0,
        "spam": 0,
        "waiting": 0,
        "unreceived": 0
      }
    }
  }
}

Run a deliverability test

/api/v2/mailboxes/{mailbox_id}/deliverability_checkers

Headers:

Parameters:

• mailbox_id* (your mailbox number)

{ "uniq_token": "string" }

Get full info about deliverability checker

/api/v2/mailboxes/{mailbox_id}/deliverability_checkers/{uniq_token} 

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)
• page 
• per_page
  
  

Parameters:

• mailbox_id* (your mailbox number)
• uniq_token * (Deliverability checker uniq_token)

Get a list of deliverability tests

/api/v2/mailboxes/{mailbox_id}/deliverability_checkers

Headers:

Parameters:

• mailbox_id* (your mailbox number)

{
  "items": [
    {
      "title": "string",
      "uniq_token": "string",
      "created_date": "string",
      "stats": {
        "inbox": 0,
        "spam": 0,
        "waiting": 0,
        "not_received": 0
      }
    }
  ],
  "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
  }
}

Run a deliverability auto-test

/api/v2/mailboxes/{mailbox_id}/deliverability_checkers/toggle_auto_checker

Description:

next_check_date date format: %Y-%m-%d

Headers:

Parameters:

• mailbox_id* (your mailbox number)

{
  "mailbox": {
    "auto_checker_attributes": {
      "active": true
    }
  }
}

Change deliverability auto-test settings of multiple mailboxes

/api/v2/deliverability_checkers/mass_update_auto_checker

Description:

mailbox_ids can be blank array and in this case changes will be applied to all mailboxes. If user_template_id will pass we set this value or set the default template if template will not be found or value is null. For stay previous template value you should remove parameter user_template_id from request.

Headers:

Example of a request body (JSON):

{
  "mailbox": {
    "active": true,
    "mailbox_ids": [
      0
    ],
    "user_template_id": 0
  }
}

DNS records test for the mailbox:

/api/v2/mailboxes/{id}/resent_health_check

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

• id* (your mailbox number)

DNS records test for all mailboxes:

/api/v2/mailboxes/health_check_by_user

Headers:

• client *
• access-token *
• uid *
• holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)