Skip to main content

Add mailboxes in bulk

Connect one or multiple mailboxes to your account by providing SMTP/IMAP credentials along with optional sending configurations. This endpoint enables you to set up the connection but you can also specify additional settings, including daily sending limits, tracking domains or footers.

You can use this endpoint to connect Gmail and Outlook mailboxes in bulk as well, provided you are using dedicated app passwords instead of regular credentials.

Request​

Endpoint​

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

Headers​

x-api-key: {YOUR_API_KEY}
Content-type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Body​

The request body contains a mailboxes array where each object represents a mailbox with its SMTP/IMAP connection credentials and optional settings (like sending limits, tracking domains, and notification preferences). You can provide one or multiple mailbox configurations in a single request.

info

You can connect up to 200 mailboxes in a single request.

{
  "mailboxes": [
    {
      "smtp_email": "smtp@mail.com",
      "smtp_login": "smtp-username",
      "smtp_password": "secret-smtp-password",
      "smtp_server": "smtp.server.io",
      "smtp_port": 465,
      "smtp_from_name": "smtp-from-name",
      "imap_email": "imap@mail.com",
      "imap_password": "secret-imap-password",
      "imap_server": "imap.server.io",
      "imap_port": 993,
      "footer": "<div>Best regards,</div><div>John</div>",
      "bcc": "email-to@bcc.com",
      "open_tracking_domain": "open-domain.com",
      "click_tracking_domain": "click-domain.com",
      "unsubscribe_tracking_domain": "unsubscribe-domain.com",
      "sending_wait_time_from": 10,
      "sending_wait_time_to": 20,
      "daily_sending_limit": 100
    }
  ],
  "completion_notification_types": ["MAIL", "IN_APP"]
}

Body schema​

FieldTypeRequiredDescription
mailboxesarrayYesArray of mailbox configurations
└─smtp_emailstringYesEmail address of the sending mail
└─smtp_loginstringNoUsername for SMTP authentication. Use if it's different than the email
└─smtp_passwordstringYesPassword for SMTP authentication
└─smtp_serverstringYesSMTP server hostname
└─smtp_portintegerYesSMTP server port number
└─smtp_from_namestringNoSender's display name shown to recipients
└─imap_emailstringYesEmail address of the receiving mail
└─imap_passwordstringYesPassword for IMAP authentication
└─imap_serverstringYesIMAP server hostname
└─imap_portintegerYesIMAP server port number
└─footerstringNoSignature added to sent emails, in HTML format
└─bccstringNoEmail address to be added as BCC in all outgoing emails. Useful with CRMs
└─open_tracking_domainstringNoCustom domain used to track email opens
└─click_tracking_domainstringNoCustom domain used to track link clicks
└─unsubscribe_tracking_domainstringNoCustom domain handling unsubscribe requests
└─sending_wait_time_fromintegerNo*Minimum pause between emails in seconds (range: 10-9999)
└─sending_wait_time_tointegerNo*Maximum pause between emails in seconds (range: 20-9999)
└─daily_sending_limitintegerNoMaximum number of sent emails allowed per day (range: 1-5500)
completion_notification_typesstring[]NoHow to notify you when batch processing completes: via email MAIL and/or in-app notification IN_APP

*Note: If either sending_wait_time_from or sending_wait_time_to is provided, both become required and from must be less than to.

Request sample​

Connect a mailbox​

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "mailboxes": [
      {
        "smtp_email": "jared@getpiedpiper.com",
        "smtp_password": "secret-smtp-password", 
        "smtp_server": "smtp.server.io",
        "smtp_port": 465,
        "imap_email": "jared@getpiedpiper.com",
        "imap_password": "secret-imap-password",
        "imap_server": "imap.server.io",
        "imap_port": 993
      }
    ]
  }'

Response​

Response examples​

The response includes a batch_id that allows you to monitor the progress and results of the submitted mailbox connections using rest/v2/mailboxes/manual_connection/bulk/{batch_id}/summary endpoint.

{
  "batch_id": 123456
}

Body schema​

FieldTypeDescription
batch_idstringID of the submitted email batch. Use it to review the connection status.