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 
• Mailbox information - Statistics for a separate mailbox
• Run a deliverability test
• 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 authentication data in headers and body

/api/v1/auth/sign_in

Headers:

holder-uid * (a66a9a755fe16f24fcb99dc8b5f25a50)

Example of a request body (JSON):

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

The response will include an access_token, uid, and client_id.

Include these headers in all subsequent API requests.

Available subscriptions on your account

/api/v2/tariff_plan_types

Headers:

• client *
• access-token *
• uid *

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:

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   
• 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:

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)

Mailbox information - Statistics for a separate mailbox

/api/v2/mailboxes/{id}

Headers:

Parameters:

• id* (your mailbox number)

Example of response (JSON):

{
  "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)

Get a list of deliverability tests

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

Headers:

Parameters:

• mailbox_id* (your mailbox number)

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)