1. Help Center
  2. General questions

How do I use Warmy with an API?

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.

Prerequisites

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.

The limit of requests is  60  per minute 
If  the number of requests is reached, you will receive an error 429

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.

Available subscriptions on your account

/api/v2/tariff_plan_types

GET

Headers:

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

Example of response (JSON):

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

Mailboxes

Connecting a new mailbox

/api/v2/mailboxes

POST

Description:

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

Fields that are required for all providers:
  • 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 group_id.
Field speed_mode can be as slow, medium, fast.
Field user_max_limit sets the maximum number of emails sent a day (according to your subscription plan).

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Example of response (JSON):
{
  "message": [
    "Your mailbox successful added"
  ],
  "data": {
    "id": 0,
    "tariff_plan_type_id": 0
  }
}

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

Example of request (JSON):

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

Request body for Outlook:

Please note that this way of connection won't work with Microsoft business. For connecting Microsoft business email address please use OAuth

Required fields:

  • Email
  • password
  • provider
  • tariff plan id

Example of request (JSON):

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

Request body for Yahoo:

Required fields:

  • Email
  • password
  • provider
  • tariff plan id

Example of request (JSON):

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

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

Example of request (JSON):

{
"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,
"group_id": integer,
 "setting_attributes": {
    "speed_mode": "string",
    "user_max_limit": integer
  }
}
}

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

Example of request (JSON):

{
"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,
"group_id": integer,
 "setting_attributes": {
    "speed_mode": "string",
    "user_max_limit": integer
  }
}
}

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   

Example of request (JSON):

{
"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",
"group_id": integer,
 "setting_attributes": {
    "speed_mode": "string",
    "user_max_limit": integer
  }
}
}

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

Example of request (JSON):

{
"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",
"group_id": integer,
 "setting_attributes": {
    "speed_mode": "string",
    "user_max_limit": integer
  }
}
}

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

Example of request (JSON):

{
"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,
"group_id": integer,
 "setting_attributes": {
    "speed_mode": "string",
    "user_max_limit": integer
  }
}
}

Change the settings of mailbox

/api/v2/mailboxes/{id}

PUT

Headers:

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

Parameters:

  • id * required (your mailbox number)

There are two forms available for setting up mailbox configuration: speed_form and detailed_form (custom form).

The speed_form allows to set the basic attributes for mailbox configuration.

Field speed_mode can be as slow, medium, fast.
Field user_max_limit sets the maximum number of emails sent a day (according to your subscription plan)

Example of a request body (JSON):

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

}
}
}

Disconnect a mailbox

/api/v2/mailboxes/{id}

DELETE

Headers:

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

Parameters:

  • id * required (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

PUT

Headers:

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

Parameters:

  • id * required (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

PUT

To deselect the subscription, you need to send "NULL".

 

Headers:

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

Parameters:

  • id * required (your mailbox number)

Example of a request body (JSON):

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

Headers:

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

Parameters:

  • id * required (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

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • page  (pagination, in: query)
  • filter[email] (filter by email)
  • filter[group_id] (filter by group)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "email": "string",
      "state": "string",
      "dns_score": 0,
      "deliverability_score": 0,
      "placement_score": 0,
      "created_at": "string",
      "received": {
        "today": 0
      },
      "sent": {
        "today": 0
      },
      "can_receive": true,
      "from_name": "string",
      "tariff_plan_type_id": 0,
      "temperature": 0,
      "bounced_state": "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
  }
}

Get Warmup deliverability statistics by Mailbox IDs

Limitation60 requests per minute from 1 IP address

/api/v2/mailboxes/warmup_statistics

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[time_bucket] * required - Determines the time bucket for statistics. 

Possible values:
hourly: Returns hourly statistics. Can only retrieve data for one day within the last 7 days.
daily: Returns daily statistics. Can retrieve data for one or more days within the last 30 days.
monthly: Returns monthly statistics. Can retrieve data for one or more months.

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

For hourly statistics: The from date can not be older than 7 days from the current date.

The from and to dates should be the same. For example:

api/v2/mailboxes/warmup_statistics?filter[time_bucket]=hourly&filter[from]=2024-08-22&filter[to]=2024-08-22&filter[mailbox_ids]=1722,2096


For daily statistics: The from date can not be older than 30 days from the current date.
For monthly statistics: The from date must be older than 30 days from the current date but cannot be earlier than 2024-01-01.

  • filter[to] - 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.
Description:
  • 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.

Example of response (JSON):

[
  {
    "mailbox_id": 0,
    "tariff_plan_type_id": 0,
    "items": [
      {
        "bucket": "string",
        "inbox": 0,
        "spam": 0
      }
    ]
  }
]

Mailbox information - Statistics for a separate mailbox

/api/v2/mailboxes/{id}

GET

Headers:

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

Parameters:

  • id * required (your mailbox number)

Example of response (JSON):

{
  "from_name": "string",
  "warmup_active": true,
  "tariff_plan_type_id": 0,
  "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
      }
    }
  }
}

Reports by user domain for the specific date

/api/v2/domain_reports

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[domain] * required (filter by domain, for example: domain.com)
  • filter[date] * required (filter by date) - Date in YYYY-MM-DD format
    (for example: 2025-02-25)

Example of response (JSON):

{
"domain": "string",
"date": "string",
"ps_reputation": "string",
"ps_date": "string",
"pc_inbox": 0,
"pc_spam": 0,
"pc_date": "string",
"w_inbox": 0,
"w_spam": 0,
"ps_user_reported_spam_ratio": 0,
"pc_spam_ratio": 0,
"w_spam_ratio": 0
}

Domain Reports by providers for the specific date

/api/v2/domain_providers

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[domain] * required (filter by domain, for example: domain.com)
  • filter[date] (filter by date) Date in YYYY-MM-DD or YYYY.MM.DD format
    (for example: 2025-02-25 or 2025.02.25)

Example of response (JSON):

{
  "items": [
    {
    "date": "string",
    "domain": "string",
    "provider": "string",
    "w_inbox": 0,
    "w_spam": 0,
    "w_spam_ratio": "0.0",
    "pc_inbox": 0,
    "pc_spam": 0,
    "pc_promotions": 0,
    "pc_spam_ratio": "0.0"
    }
  ]
}

Deliverability test

Run a deliverability test

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

POST

Description:

To run a deliverability test for specific providers, include an array of the desired provider names in the request body.
Example values for providers: GOOGLE, GSUITE, OUTLOOK, OUTLOOKBUSINESS, ZOHO, ZOHOPRO, YAHOO, OTHER 

If it is necessary to run the test for all available providers, pass an empty array for the providers field.

The ID for templates can be obtained by executing the "Get all user Template" request

Headers:

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

Parameters:

  • mailbox_id * required (your mailbox number)

Example of a request body (JSON):

{
  "user_template_id": 0,
  "providers": [
    "string"
  ]
}

Example of response (JSON):

{ "uniq_token": "string" }

Get full info about deliverability checker

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

GET


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

Parameters:

  • mailbox_id * required (your mailbox number)
  • uniq_token * required (deliverability checker uniq_token)
    (for example: SID-12040545471512)

Get a list of deliverability tests

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

GET

Headers:

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

Parameters:

  • mailbox_id * required (your mailbox number)
  • page (page number)
  • per_page (count items per page. No more 25)
Example of response (JSON):
{
  "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

PUT

Headers:

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

Parameters:

  • mailbox_id * required (your mailbox number)

Example of a request body (JSON):

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

PUT

Headers:

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

Example of a request body (JSON):

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

DNS test

DNS records test for the mailbox:

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

POST

Headers:
  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (your mailbox number)

DNS records test for all mailboxes:

/api/v2/mailboxes/health_check_by_user

POST

Headers:

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

Warm-up Alerts:

Retrieve the list of Alerts

/api/v2/warmup_alerts

GET

Description:

  • Optional filter like filter[domain]=specific domain.
  • Options keys: stop_sending_emailsunblock_your_ipchange_your_email_templaterecheck_your_reputation_on_spamhouscheck_your_dkim_spf

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[domain] (filter by domain, for example: domain.com)
  • filter[alert_key] filter by alert_key. Possible values: reject_domain_by_receiver_provider
  • filter[viewed] (filter by viewed. Possible values: true/false)
  • filter[state] (filter by state. Possible values: not completed/processing/checking/failed/success)
  • page (page number)
  • per_page (items on the page)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "domain": "string",
      "alert_key": "string",
      "target_provider": "string",
      "state": "string",
      "viewed": true,
      "finished": true,
      "checked_at": "string",
      "options": {
        "some_key_1": {
          "key": "string",
          "required": true,
          "value": true
        },
        "some_key_2": {
          "key": "string",
          "required": true,
          "value": true
        }
      }
    }
  ]
}

Update Alert status

/api/v2/warmup_alerts/{id}

PUT

Description:

With this endpoint you can change only next fields:
1 - :finished, only into true for alerts with statuses failed or success
2 - :options, only nested field "value". Also for required options you can just set it true
For not required options you can set it to true or false values.
About unsuccessful attempts to update these fields there will be a related error in the data object in response
All invalid or unacceptable parameters will be ignored without error.
Correct keys for option properties for the alert you can get here /api/v2/warmup_alerts.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required  (warm-up Alert id)

Example of a request body (JSON):

{
  "finished": true,
  "options": {
    "some_key_1": {
      "value": true
    },
    "some_key_2": {
      "value": true
    }
  }
}
Example of response (JSON):
{
  "id": 0,
  "domain": "string",
  "alert_key": "string",
  "target_provider": "string",
  "state": "string",
  "viewed": true,
  "finished": true,
  "checked_at": "string",
  "options": {
    "some_key_1": {
      "key": "string",
      "required": true,
      "value": true
    },
    "some_key_2": {
      "key": "string",
      "required": true,
      "value": true
    }
  }
}

Mailboxes Groups

Create new user Group

/api/v2/groups

POST

Headers:

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

Example of a request body (JSON):

{
  "group": {
    "name": "string"
  }
}

Example of response (JSON):

Success created group:

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

Failed created group:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Get user Groups

/api/v2/groups

Returns only id and name. Filtering allowed fields: name.

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[name] (filter by name)
  • page (page number)
  • per_page (count items per page)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "name": "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
  }
}

Get Groups statistics

/api/v2/groups/stats

Returns groups with detailed statistics including mailbox counts by status.

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[name] (filter by name)
  • page (page number)
  • per_page (count items per page)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "name": "string",
      "mailbox_count": 0,
      "active_mailbox_count": 0,
      "blocked_count": 0,
      "without_imap_count": 0,
      "on_hold_count": 0,
      "low_deliverability_count": 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
  }
}

 Get Group statistics

/api/v2/groups/{id}/stats

 Returns detailed statistics for a specific group.

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (group id)

Example of response (JSON):

Group statistics:

{
  "id": 0,
  "name": "string",
  "mailbox_count": 0,
  "active_mailbox_count": 0,
  "blocked_count": 0,
  "without_imap_count": 0,
  "on_hold_count": 0,
  "low_deliverability_count": 0
}

 Group not found:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Get Mailboxes that are not Grouped

/api/v2/groups/mailboxes/no_grouped

Get mailboxes that are not grouped.

GET

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[email] (filter by email)
  • filter[providers] (filter by provider)
  • filter[domains] (filter by domain)
  • sorting[email] (sort by email)
  • page (page number)
  • per_page (per page)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "email": "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
  }
}

Assign Mailboxes to a Group

/api/v2/groups/{group_id}/mailbox_assignments

Assign specific mailboxes to a group by providing mailbox_ids.

POST

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • group_id * required (group id)

Example of a request body (JSON):

{
  "mailbox_assignment": {
    "mailbox_ids": [
      "string"
    ]
  }
}

Example of response (JSON):

Group not found:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Unassign Mailboxes from a Group

/api/v2/groups/{group_id}/mailbox_assignments

Unassign specific mailboxes from a group by providing mailbox_ids.

DELETE

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • group_id * required (group id)

Example of a request body (JSON):

{
  "mailbox_assignment": {
    "mailbox_ids": [
      "string"
    ]
  }
}

Example of response (JSON):

Group not found:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Update user Group

/api/v2/groups/{id}

PUT

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (group id)

Example of a request body (JSON):

{
  "group": {
    "name": "string"
  }
}

Example of response (JSON):

Success updated group:

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

Failed updated group:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Destroy user Group

/api/v2/groups/{id}

DELETE

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (group id)

Example of response (JSON):

Failed deleted group:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Mass destroy user Groups

/api/v2/groups/mass_destroy

POST

Headers:

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

Example of a request body (JSON):

{
  "group": {
    "ids": [
      "string"
    ]
  }
}

Example of response (JSON):

Failed deleted groups:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

User Templates

Create user Template

/api/v2/user_templates

POST

Description:

The subject max length is 100 characters
The appearance must be one of "text" or "html", default - "text". 
The default name value is today's date in "Jan 01, 2000" format.
The “body” field, if the template is text, must contain .
The "language_code" field must be in the ISO 639-1 standard format. For example, use «en» for the English language.

Headers:

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

Example of a request body (JSON):

{
  "user_template": {
    "subject": "string",
    "body": "string",
    "language_code": "string",
    "appearance": "string",
    "name": "string"
  }
}

Example of response (JSON):

Created new user template:

{
  "message": "You successfully created template",
  "id": 0
}

Failed created template:

{
  "errors": [
    "string"
  ]
}

Get one user Template

/api/v2/user_templates/{id}

GET

Description:

The moderation_state field can have one of the following values: approved, rejected, or pending.
The provider field will have one of the following values: warmy or hubspot.
The appearance field will have one of the following values: html or text

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (user template id)

Example of response (JSON):

{
  "id": 0,
  "warming": true,
  "provider": "string",
  "appearance": "string",
  "moderation_state": "string",
  "name": "string",
  "created_at": "string",
  "updated_at": "string",
  "subject": "string",
  "body": "string",
  "language": {
    "name": "string",
    "code": "string"
  }
}
Template not found:
{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Get all user Template

/api/v2/user_templates

GET

Description:

The moderation_state field can have one of the following values: approved, rejected, or pending.
The provider field will have one of the following values: warmy or hubspot.
The appearance field will have one of the following values: html or text. By default, it is set to text.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[name] (filter templates by name)
  • filter[searchable] (filter templates by name or subject)
  • filter[subject] (filter templates by subject)
  • filter[appearance] (filter templates by appearance)
  • filter[moderation_state] (filter templates by moderation state)
  • page (page number)
  • per_page (per page number. default - 20)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "warming": true,
      "provider": "string",
      "appearance": "string",
      "moderation_state": "string",
      "name": "string",
      "created_at": "string",
      "updated_at": "string",
      "subject": "string",
      "body": "string",
      "language": {
        "name": "string",
        "code": "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
  }
}

Update user Template

/api/v2/user_templates/{id}

PUT

Description:

The subject max length is 100 characters
The appearance must be one of "text" or "html", default - "text". 
The default name value is today's date in "Jan 01, 2000" format.
The “body” field, if the template is text, must contain .
The warming is set to true only if the template has any mailboxes assigned.
The "language_code" field must be in the ISO 639-1 standard format. For example, use «en» for the English language.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (user template id)

Example of a request body (JSON):

{
  "user_template": {
    "subject": "string",
    "body": "string",
    "warming": true,
    "language_code": "string",
    "appearance": "string",
    "name": "string"
  }
}

Example of response (JSON):

Update user template:

[
    "You successfully updated template"
]

Failed updated template:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Delete user Template

/api/v2/user_templates/{id}

DELETE

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • id * required (group id)

Example of response (JSON):

Failed deleted group:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

User templates stats

/api/v2/user_templates/stats

GET

Description:

The moderation_state field can have one of the following values: approved, rejected, or pending.
The provider field will have one of the following values: warmy or hubspot.
The appearance field will have one of the following values: html or text. By default, it is set to text.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[name] (filter templates by name)
  • filter[searchable] (filter templates by name or subject)
  • filter[subject] (filter templates by subject)
  • filter[appearance] (filter templates by appearance)
  • filter[moderation_state] (filter templates by moderation state)
  • page (page number)
  • per_page (per page number. default - 20)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "name": "string",
      "subject": "string",
      "sent": {
        "total": 0
      },
      "replies": {
        "total": 0
      },
      "deliverability": {
        "inbox": 0,
        "spam": 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
  }
}

Update assigned user templates

/api/v2/user_templates_assignments/:assignment_type/:assignment_value/bulk_update

POST

Description:

The assignment_type can be one of the following: group, credential, or domain.

For assignment_type as group, or credential, the assignment_value should be the ID of the respective type in the system.
The ID for group can be obtained by executing the "Get Groups statistics" request, and the ID for credential (mailbox id) can be retrieved by executing the "List of Mailboxes with statistics" request.

For domain, the assignment_value must be the domain name, with %2E replacing the dot (e.g., example.com becomes example%2Ecom).

The user_template_ids is an array of user template IDs to be assigned to the specified group, credential, or domain.

For the response:

  • user_template_ids will contain the list of user template IDs successfully assigned.

  • skipped_ids will include any user template IDs that were not assigned, due to reasons like the template not belonging to the user, not being found, etc.

  • message will provide additional information about the operation, such as partial success or success.

If the assignment_type does not belong to a user, does not exist, or if the domain is shared, the system will raise a 404 - Not Found error.

Important: During the update operation, only the passed user template IDs will be stored. All other previously assigned templates will be removed. For instance, if IDs [1, 3] are assigned and you provide [2, 3], template 1 will be removed and template 2 will be assigned.

Headers:

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

Example of a request body (JSON):

Bulk user templates update

{
  "user_template_ids": [
    0
  ]
}

Example of response (JSON):

Bulk user templates update

{
  "user_template_ids": [
    0
  ],
  "skipped_ids": [
    0
  ],
  "message": "Partial success: 1 item(s) skipped"
}

Not found template:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}

Select available user Templates

/api/v2/user_templates_assignments/:assignment_type/:assignment_value/user_templates

GET

Description:

The assignment_type can be one of the following: group, credential, or domain.

For assignment_type as group, or credential, the assignment_value should be the ID of the respective type in the system.
The ID for group can be obtained by executing the "Get Groups statistics" request, and the ID for credential (mailbox id) can be retrieved by executing the "List of Mailboxes with statistics" request.

For domain, the assignment_value must be the domain name, with %2E replacing the dot (e.g., example.com becomes example%2Ecom).

The moderation_state field can have one of the following values: approved, rejected, or pending.
The provider field will have one of the following values: warmy or hubspot.
The appearance field will have one of the following values: html or text. By default, it is set to text.

Headers:

  • Authorization * required (Bearer your_token)
  • holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Parameters:
  • filter[name] (filter templates by name)
  • filter[searchable] (filter templates by name or subject)
  • filter[subject] (filter templates by subject)
  • filter[appearance] (filter templates by appearance)
  • filter[moderation_state] (filter templates by moderation state)
  • page (page number)
  • per_page (per page number. default - 20)

Example of response (JSON):

{
  "items": [
    {
      "id": 0,
      "warming": true,
      "provider": "string",
      "appearance": "string",
      "moderation_state": "string",
      "name": "string",
      "created_at": "string",
      "updated_at": "string",
      "subject": "string",
      "body": "string",
      "language": {
        "name": "string",
        "code": "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
  }
}

Not found template:

{
  "errors": {
    "field_name": [
      "string"
    ]
  }
}