- Using Warmy with an API
- YAML file
- Server
- Authentication via API_KEY
- Available subscriptions on your account
- Mailboxes
- 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
- Reports by user domain for the specific date
- Domain Reports by providers for the specific date
- Deliverability test
- DNS test
- Warm-up Alerts
- Mailboxes Groups
- User Templates
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.
PrerequisitesBefore you can use the API, you need to already be registered on warmy.io
YAML file:
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
GET
Headers:
-
Authorization * required (Bearer your_token)
- holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
Example of response (JSON):
[
{
"id": 0,
"name": "string"
}
]
Mailboxes
Connecting a new mailbox
POST
Description:
Available providers: Gmail, Outlook, Yahoo, Mailgun, SendGrid, OAuth Google, OAuth Outlook.
Fields that are required for all providers:- provider
- 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)
{
"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:
Request body for Gmail:
Required fields:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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
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
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
}
}
Reconnect the mailbox
Instruction for reconnecting OAuth Google here
Instruction for reconnecting OAuth Outlook here
For all other providers:
/api/v2/mailboxes/{id}/reconnect
POST
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)
- 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
/api/v2/mailboxes/warmup_statistics
GET
Headers:
-
Authorization * required (Bearer your_token)
- holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
- 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.
- 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)
- 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)
- 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)
{
"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
-
Authorization * required (Bearer your_token)
- holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
- 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_emails
,unblock_your_ip
,change_your_email_template
,recheck_your_reputation_on_spamhous
,check_your_dkim_spf
Headers:
-
Authorization * required (Bearer your_token)
- holder-uid * required (a66a9a755fe16f24fcb99dc8b5f25a50)
- 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)
- id * required (warm-up Alert id)
Example of a request body (JSON):
{Example of response (JSON):
"finished": true,
"options": {
"some_key_1": {
"value": true
},
"some_key_2": {
"value": true
}
}
}
{
"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)
- 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)
- 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)
- 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)
- 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)
- 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)
- 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)
- 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)
- 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)
- id * required (user template id)
Example of response (JSON):
{Template not found:
"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"
}
}
{
"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)
- 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)
- 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)
- 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)
- 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)
- 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"
]
}
}