We use cookies. Read Privacy Policy
Maildoso API
Learn how to connect, automate, and manage Maildoso features using our API documentation.
Introduction
Maildoso is a professional email infrastructure platform that enables you to register domains and create unlimited email accounts for your cold outreach operations. Our API provides programmatic access to manage your entire email infrastructure, from domain registration to account provisioning and deliverability optimization.
Authentication
All API requests require authentication using a Personal Access Token (PAT).
How to Get Your PAT
- Log in to your Maildoso account at app.maildoso.com
- Navigate to Settings → API Keys
- Copy your token and store it securely
- Use the token in the Authorization header for all API requests
⚠️ Security Best Practices:
- Never share your PAT or commit it to public repositories
- Store tokens securely using environment variables or secret management tools
- Rotate tokens periodically for enhanced security
- Each PAT has full access to your account – treat it like a password
Quick Start Guide
Ready to build with Maildoso? Here's your roadmap:
- Authentication - Get your PAT and make your first API call
- Domains API - Register and manage domains
- Email Accounts API - Create and configure email accounts
- Forwarding API - Set up email forwarding rules
Need Help?
Contact our support team for assistance
Maildoso MCP Server
This MCP server exposes endpoints for Model Context Protocol (MCP) tools.
Obtain a Personal Access Token (PAT)
Follow the instruction in the Introduction section to get your PAT.
Connect to Maildoso MCP Server
Follow the instructions below to connect your MCP client to the Maildoso MCP server.
n8n agent:
- In n8n, add AI agent node.
- For the tool connection, add MCP client tool node.
- In MCP Client parameters, add new MCP server with the following configuration:
- SSE endpoint: https://mcp.maildoso.com/sse
- Authentication: Bearer auth. Use your PAT as the token.
Claude Desktop:
In Claude Desktop, navigate to Settings.
Select Developer section. Under Local MCP servers click Edit config.
Open selected file (claude_desktop_config.json) in a text editor.
Add the following MCP server configuration to the mcpServers section:
"maildoso-api": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.maildoso.com/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer <YOUR_PAT_TOKEN>"
}
}
Select Developer section. Under Local MCP servers click Edit config.
Open selected file (claude_desktop_config.json) in a text editor.
Add the following MCP server configuration to the mcpServers section:
"maildoso-api": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.maildoso.com/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer <YOUR_PAT_TOKEN>"
}
}
Other MCP Clients:
Refer to your MCP client's documentation on how to add custom MCP servers. Use the URL https://mcp.maildoso.com/mcp for streaming http transport or https://mcp.maildoso.com/sse for SSE transport and include the Authorization` header with your Personal Access Token (PAT), for example:
Header: Authorization
Value: Bearer <YOUR_PAT_TOKEN>
Header: Authorization
Value: Bearer <YOUR_PAT_TOKEN>
Users
Manage user profiles, authentication tokens, and tenant settings.
Get user data
Retrieves user's personal and company data required for domain registration with ICANN-compliant registrars.
Get user
Get current authenticated user. Creates user in DB on first request.
Get user settings
Get user settings including Personal Access Token
Get stats
Get user resource quotas showing allocated and used resources for different resource types.
The available count for each resource is calculated as:
available = total - in_use
The available count for each resource is calculated as:
available = total - in_use
Set user data
Creates user registration data for ICANN-compliant registrars.
Regenerate user PAT
Deletes the existing PAT token and creates a new one
Update user data
Partially updates user registration data by modifying only the provided fields.
Accounts
Provision, update, and retire individual email accounts.
Lookup User Email Accounts
Generate Account Totp
Generate TOTP for an email account.
This endpoint uses the EmailProviderService to generate a TOTP code for the account. Currently supports Google accounts.
Args: account_id: Email account ID email_provider_service: Service for provider-specific operations db: Database adapter user: Current authenticated user
Returns: TOTPResponse with generated TOTP code and expiration timestamp
Raises: HTTPException: 400 if provider not supported or credentials missing, 403 if user doesn't own the account, 404 if account not found, 400 if account status is not ACTIVE, 500 if provider API fails
This endpoint uses the EmailProviderService to generate a TOTP code for the account. Currently supports Google accounts.
Args: account_id: Email account ID email_provider_service: Service for provider-specific operations db: Database adapter user: Current authenticated user
Returns: TOTPResponse with generated TOTP code and expiration timestamp
Raises: HTTPException: 400 if provider not supported or credentials missing, 403 if user doesn't own the account, 404 if account not found, 400 if account status is not ACTIVE, 500 if provider API fails
Get user forwarding accounts
Create user email accounts
Change user email account
Change account forwarding address
Delete user email accounts
Delete one or more email accounts.
Deleting mailboxes permanently removes all messages associated with the accounts. Back up or save critical correspondence before proceeding.
- Maildoso accounts are deleted immediately.
- Google Workspace accounts are scheduled for deletion at the next account renewal date:
- created Jan 15, deleted Mar 10 → scheduled for Apr 15
- created Jan 15, deleted Mar 27 → scheduled for Apr 15
- created Jan 31, deleted Feb 27 → scheduled for Mar 31
- created Jan 31, deleted Jan 15 → scheduled for Feb 28
Deleting mailboxes permanently removes all messages associated with the accounts. Back up or save critical correspondence before proceeding.
Domains
Register domains and manage domain lifecycle.
Get user domains
Retrieves all domains associated with the current user. Supports filtering by keyword, type, provider, IDs, date range, and ordering.
Check domain availability for providers
Check if domains are available for use with different email providers (Google Workspace, Maildoso).
Create user domains
Creates and buys domains for a user. Those TLDs not allowed for registration: .ca, .app, .cloud, .site, .tech, .xyz, .eu, .us, .fr, .nl
Create External Domains
Add external domains to your account
External domains are domains registered with third-party registrars (GoDaddy, Dynadot, Namecheap, etc.) that you want to use with Maildoso email services.
After adding an external domain, you must configure the required Name Server (NS) records at your registrar within 24 hours.
You can retrieve the list of domains and their corresponding NS records using the following endpoint: https://developers.maildoso.com/#tag/domains/GET/v1/user/domains
NS configuration steps:
If you submit a domain that already exists in your account:
External domains are domains registered with third-party registrars (GoDaddy, Dynadot, Namecheap, etc.) that you want to use with Maildoso email services.
After adding an external domain, you must configure the required Name Server (NS) records at your registrar within 24 hours.
You can retrieve the list of domains and their corresponding NS records using the following endpoint: https://developers.maildoso.com/#tag/domains/GET/v1/user/domains
NS configuration steps:
- Retrieve list of domains with NS
- Add NS records to your registrar
- Wait for the domain status to change to “ACTIVE”. This usually takes up to 2 hours.
If you submit a domain that already exists in your account:
- Domains with status ACTIVE will be returned as is and will not be reconfigured.
- Domains with any other status will be reconfigured, and new NS records will be regenerated.
Restart Domain Setup
Restart the setup process for existing domains in the user's account.
This is useful if the initial setup failed or if DNS records were not configured correctly.
This is useful if the initial setup failed or if DNS records were not configured correctly.
Search domains
Searches for domains to register with optional variations. Those TLDs not allowed: .ca, .app, .cloud, .site, .tech, .xyz, .eu, .us, .fr, .nl
Change user domain settings
Updates user domains' settings such as redirect URLs.
Enable or disable GCDT feature
Toggle the global tracking state for the current user. This endpoint is used to enable or disable the GCDT feature. By default, the state is True, which means the GCDT feature is enabled.
Forwarding
A forwarding account is a centralized inbox that aggregates replies and inbound emails from multiple campaign sending addresses into a unified @maildoso.email address where all responses can be read and managed in one place.
When you reply to a lead from the forwarding account, the system automatically substitutes the sender - the email is actually sent from the original campaign address that the lead replied to, maintaining conversation threading and sender authenticity.
When you reply to a lead from the forwarding account, the system automatically substitutes the sender - the email is actually sent from the original campaign address that the lead replied to, maintaining conversation threading and sender authenticity.
Lookup forwarding accounts
Retrieve and filter forwarding accounts for the authenticated user.
Use this endpoint to search, filter, sort, and paginate through your forwarding accounts. It returns detailed information about each forwarding account including attached email accounts, IMAP/SMTP server configuration, and server credentials.
Use this endpoint to search, filter, sort, and paginate through your forwarding accounts. It returns detailed information about each forwarding account including attached email accounts, IMAP/SMTP server configuration, and server credentials.
Create forwarding address
Create a new forwarding address for the authenticated user.
Use this endpoint to create a forwarding account with an associated email account. The system automatically handles domain setup and email account creation. A strong password is auto-generated.
⚠️ Domain restriction
Only maildoso.email domain is supported for forwarding accounts. Forwarding addresses use the format username@maildoso.email.
Use this endpoint to create a forwarding account with an associated email account. The system automatically handles domain setup and email account creation. A strong password is auto-generated.
⚠️ Domain restriction
Only maildoso.email domain is supported for forwarding accounts. Forwarding addresses use the format username@maildoso.email.
Reset password for forwarding address
Use this endpoint to reset or change the password for a forwarding account.
This endpoint allows users to securely reset their forwarding account password. The system enforces strict password requirements, validates account ownership, and synchronizes the password change.
ℹ️ Password details
A password is automatically generated if not provided.
Requirements:
This endpoint allows users to securely reset their forwarding account password. The system enforces strict password requirements, validates account ownership, and synchronizes the password change.
ℹ️ Password details
A password is automatically generated if not provided.
Requirements:
- Minimum 12 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one digit (0-9)
Delete forwarding addresses
Delete one or more forwarding accounts in bulk.
Use this endpoint to batch-delete forwarding accounts.
The system automatically resets forwarding account references on any linked email accounts to maintain referential integrity.
ℹ️ Data preservation
Underlying email accounts created during forwarding setup are preserved. Only the forwarding configuration is removed, not the actual email accounts.
Use this endpoint to batch-delete forwarding accounts.
The system automatically resets forwarding account references on any linked email accounts to maintain referential integrity.
ℹ️ Data preservation
Underlying email accounts created during forwarding setup are preserved. Only the forwarding configuration is removed, not the actual email accounts.
Warmups
Warm-up emails are automatically generated messages used to improve deliverability.
They create a lot of artificial traffic that should not appear in your forwarding accounts, otherwise you cannot clearly see real replies from prospects and customers.
Add your warmup service with warmup_exclude tags to avoid sending them to your forwarding accounts.
They create a lot of artificial traffic that should not appear in your forwarding accounts, otherwise you cannot clearly see real replies from prospects and customers.
Add your warmup service with warmup_exclude tags to avoid sending them to your forwarding accounts.
Get user warmup services
Returns the list of warm-up services configured for the current user.
Use this endpoint to see which external warm-up tools (Smartlead, Instantly, Allegrow, etc.) are currently connected and how they are identified by tags.
Use this endpoint to see which external warm-up tools (Smartlead, Instantly, Allegrow, etc.) are currently connected and how they are identified by tags.
Create user warmup services
Creates a new warm-up service configuration for the current user.
Use this endpoint after connection of your email accounts to a new warm-up tool. You need to define tags to filter warm-up emails from your forwarding accounts.
ℹ️ Note
Requires warmup_meta.api_key for the system_id=smartlead and rejects it for other providers.
Use this endpoint after connection of your email accounts to a new warm-up tool. You need to define tags to filter warm-up emails from your forwarding accounts.
ℹ️ Note
Requires warmup_meta.api_key for the system_id=smartlead and rejects it for other providers.
Update user warmup services
Updates the configuration of warm-up services by warmup_ids.
This is useful when you want to refine how warm-up emails are filtered out of your forwarding account.
This is useful when you want to refine how warm-up emails are filtered out of your forwarding account.
Delete user warmup service
Deletes a warm-up service configuration for the current user.
Use this endpoint when you no longer use a specific warm-up provider, or you want to stop applying its warm-up filtering rules.
Use this endpoint when you no longer use a specific warm-up provider, or you want to stop applying its warm-up filtering rules.
Sequencers
Connect your favourite sequencer and export your email accounts.
Get user sequencers
Retrieve all available sequencer platforms with user connection status.
Add a new sequencer
Create a new sequencer instance for the authenticated user.
Export To Sequencer
Export email accounts to a sequencer.
The export status can be found in exported_to_sequencers attribute in the email account object.
The export status can be found in exported_to_sequencers attribute in the email account object.
Update an existing sequencer
Update an existing sequencer's configuration.
Conclusion
Cold emailing is one of the most practical ways to start a professional conversation with someone who hasn’t interacted with your business before. While often misunderstood or compared to spam or email marketing, cold emails serve a very different purpose, to create a personalized, targeted connection. Whether the goal is lead generation, hiring, partnerships, or networking, cold email allows teams to reach out directly and efficiently.
That said, success with cold emailing doesn’t come from guesswork. It requires the right setup, clear messaging, legal compliance, and ongoing effort to improve results. For anyone looking to build business relationships or expand their reach, understanding how cold email works, and how to do it properly, is a valuable skill in today’s digital-first environment.
That said, success with cold emailing doesn’t come from guesswork. It requires the right setup, clear messaging, legal compliance, and ongoing effort to improve results. For anyone looking to build business relationships or expand their reach, understanding how cold email works, and how to do it properly, is a valuable skill in today’s digital-first environment.
Related articles
Most cold emails fail simply because they land in spam. People never even see your offer. Our SMTP and Google Workspace mailboxes are built specifically for outbound; this means your emails will finally be seen, and you’ll start getting more positive replies.
Boost your outbound with our infrastructure!
BacklinkSwappers, inc.
1390 Market Street
Suite 200
San Francisco, CA 94102
1390 Market Street
Suite 200
San Francisco, CA 94102
Company
Legal
Product
Resources
