Adding mailboxes | Woodpecker.co Help Center

⚠️ You can find the new and up-to-date documentation here ⚠️

Submit a batch of mailboxes (manual connections)

To submit a batch of mailboxes to your Woodpecker account, use the following request:

POST https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk

{
    "mailboxes": [
        {
            "smtp_email": string,
            "smtp_login": string,
            "smtp_password": string,
            "smtp_server": string,
            "smtp_port": integer,
            "smtp_from_name": string,
            "imap_email": string,
            "imap_password": string,
            "imap_server": string,
            "imap_port": integer,
            "footer": string,
            "bcc": string
            "open_tracking_domain": string,
            "click_tracking_domain": string,
            "unsubscribe_tracking_domain": string,
            "sending_wait_time_from": integer,
            "sending_wait_time_to": integer,
            "daily_sending_limit": integer
        }
    ],
    "completion_notification_types": [
        "MAIL"
    ]
}

Request type data:

Field	Data Type	Requirements
`mailboxes.smtp_email`	`string`	Provided and valid email address.
`mailboxes.smtp_login`	`string`	If provided, it must not be blank.
`mailboxes.smtp_password`	`string`	Provided and not blank.
`mailboxes.smtp_server`	`string`	Provided and not blank.
`mailboxes.smtp_port`	`integer`	Provided and in range <1; 65535>.
`mailboxes.smtp_from_name`	`string`	If provided, must not be blank.
`mailboxes.imap_email`	`string`	Provided and valid email address.
`mailboxes.imap_password`	`string`	Provided and not blank.
`mailboxes.imap_server`	`string`	Provided and not blank.
`mailboxes.imap_port`	`integer`	Provided and in range <1; 65535>.
`mailboxes.footer`	`string`	If provided, it must not be blank.
`mailboxes.bcc`	`string`	If provided, it must be a valid email address.
`open_tracking_domain`	`string`	If provided must be a valid domain.
`click_tracking_domain`	`string`	If provided must be a valid domain.
`unsubscribe_tracking_domain`	`string`	If provided must be a valid domain.
`sending_wait_time_from`	`integer`	If provided must be in range <10,9999> and smaller than `sending_wait_time_to`. Requires `sending_wait_time_to` to be provided.
`sending_wait_time_to`	`integer`	If provided must be in range <20,9999> and bigger than `sending_wait_time_from`. Requires `sending_wait_time_from` to be provided.
`daily_sending_limit`	`integer`	If provided must be in range <1,5500>.
`completion_notification_types`	`string[]`	Determine whether to send a notification after this batch processing. Possible values: `MAIL` - mail notification When `null` or empty, no notification will be sent (default behavior).

Successful response

HTTP: 202 ACCPETED
BODY:
{
    "batch_id": integer
}

Response type data:

Field	Data Type	Description
`batch_id`	`integer`	The ID of the successfully submitted batch. It could be further used to get batch summaries.

Unsuccessful response

HTTP: 400 BAD REQUEST | 409 CONFLICT | 500 INTERNAL SERVER ERROR
BODY:
{
    "code": string,
    "details": [
        string
    ]
}

Response data type:

Field	Data Type	Description
`code`	`string`	Informative code that describes the request problem. Could be one of the following: `VALIDATION_FAILURE` - when there is a problem with any of the requested mailboxes or the list of requested mailboxes is empty or contains more than 200 elements `UNKNOWN` - when unexpected error occured
`details`	`string[]`	List of strings with error details.

Get batch summary

To get a status/summary of adding the batch of mailboxes, use the following request:

GET https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk/{batch_id}/summary

Request data type:

batch_id – batch identifier;

Successful response

HTTP: 200 OK
BODY:
{
    "processing_finished": boolean,
    "batch_size": integer,
    "pending_mailboxes_count": integer,
    "connected_mailboxes_count": integer,
    "conditionally_connected_mailboxes_count": integer,
    "conditionally_connected_mailboxes": [
        {
            "connection_request_id": integer,
            "smtp_email": string,
            "smtp_login": string,
            "imap_email": string,
        }
    ]
    "failed_mailboxes": [
        {
            "connection_request_id": integer,
            "smtp_email": string,
            "smtp_login": string,
            "imap_email": string,
            "error_message": string
        }
    ]
}

Response data type:

Field	Data Type	Description
`processing_finished`	`boolean`	Indicates whether this batch processing was already finished or not.
`batch_size`	`integer`	Defines how many mailboxes there were in batch.
`pending_mailboxes_count`	`integer`	Defines how many mailboxes are still pending for processing.
`connected_mailboxes_count`	`integer`	Defines how many mailboxes were successfully connected.
`conditionally_connected_mailboxes.connection_request_id`	`integer`	Unique ID of individual failed mailbox connection request.
`conditionally_connected_mailboxes.smtp_email`	`string`	Smtp email of conditionally connected mailbox connection request.
`conditionally_connected_mailboxes.smtp_login`	`string`	Smtp login of conditionally connected mailbox connection request (might be null if not provided in request).
`conditionally_connected_mailboxes.imap_email`	`string`	IMAP email of a conditionally connected mailbox connection request.
`failed_mailboxes.connection_request_id`	`integer`	Unique ID of individual failed mailbox connection request.
`failed_mailboxes.smtp_email`	`string`	Smtp email of failed mailbox connection request.
`failed_mailboxes.smtp_login`	`string`	Smtp login of failed mailbox connection request (might be null if not provided in request).
`failed_mailboxes.imap_email`	`string`	Imap email of failed mailbox connection request.
`failed_mailboxes.error_message`	`string`	Error reason related to failed mailbox connection request.

Unsuccessful response

HTTP: 404 NOT FOUND

When the batch with the given ID was not found.