Domains
The /domains API lets you purchase domains and mailboxes that are preconfigured for cold emailing and ready to use in Woodpecker. You can also check domain availability, save domain owner details, list ordered and purchased domains and mailboxes with their statuses, and manage domain-level settings such as redirect URLs and email forwarding.
Before placing an order, use the provider and availability endpoints to check available options and pricing. Domain orders require domain owner details, so create or update them first if they are not saved in the account yet. After a domain is active, you can order additional mailboxes for it or update its redirect and forwarding settings.
Some operations create billable assets. Domain and mailbox purchases are paid from prepaid funds. After purchase, mailbox renewals are covered by your regular monthly Woodpecker billing cycle.
Purchase flow
- Check your prepaid funds in Woodpecker. If the balance is too low, add prepaid funds before placing an order.
- Use Get providers to review available providers and mailbox pricing, then use Search domain availability or Check domain availability to find domains you can buy.
- Use Get domain owner to check the saved owner details. If this is your first domain purchase or the details have changed, use Save domain owner before ordering.
- Place the order for domain and mailboxes with Order domains. To add mailboxes to an existing active domain, use Order mailboxes.
- Domain and mailbox orders are processed asynchronously. After the order is accepted, use List domains, Get domain details, List domain mailboxes, or Get domain mailbox to check whether the domain is ready and whether ordered mailboxes are paid and available.
- After the domain and mailboxes are ready, adjust domain and mailbox settings if needed. Redirect URL and email forwarding can use defaults saved in the owner configuration, or you can update them with Set redirect URL and Set email forwarding. Use Update mailbox profile picture to set mailbox avatars.
Available endpoints
The table below lists every documented endpoint under /rest/v2/domains.
| Endpoint | Method and path | Use it to |
|---|---|---|
| Get providers | GET /rest/v2/domains/providers | Retrieve providers available for domain orders, including mailbox prices |
| Search domain availability | GET /rest/v2/domains/availability | Search available domains by phrase |
| Check domain availability | POST /rest/v2/domains/availability | Check a specific list of domains |
| Get domain owner | GET /rest/v2/domains/owner | Retrieve saved domain owner details |
| Save domain owner | POST /rest/v2/domains/owner | Create or update domain owner details |
| Order domains | POST /rest/v2/domains/order | Order domains and mailboxes together |
| Order mailboxes | POST /rest/v2/domains/mailboxes/order | Order mailboxes for existing active domains |
| List domains | GET /rest/v2/domains | Retrieve domains that belong to your account |
| Get domain details | GET /rest/v2/domains/{domain_name} | Retrieve owner, settings, and mailbox summary for one domain |
| List domain mailboxes | GET /rest/v2/domains/{domain_name}/mailboxes | Retrieve mailboxes that belong to one domain |
| Get domain mailbox | GET /rest/v2/domains/{domain_name}/mailboxes/{mailbox_email} | Retrieve mailbox details and connection settings |
| Update mailbox profile picture | PATCH /rest/v2/domains/{domain_name}/mailboxes/{mailbox_email}/profile_picture | Update a mailbox profile picture |
| Set redirect URL | PATCH /rest/v2/domains/{domain_name}/set_redirect_url | Update the redirect URL for a domain |
| Set email forwarding | PATCH /rest/v2/domains/{domain_name}/set_email_forwarding | Update the forwarding address for a domain |
| Delete domain | DELETE /rest/v2/domains/{domain_name} | Delete a domain from Woodpecker |
| Delete mailbox | DELETE /rest/v2/domains/{domain_name}/mailboxes/{mailbox_email} | Delete a mailbox from a domain |