How to use the Mailforge API

The Mailforge API allows you to automate common Mailforge infrastructure workflows, such as managing workspaces, checking domain availability, purchasing domains, creating mailboxes, reviewing DNS records, configuring forwarding, and managing mailbox data.

It is useful when your team wants to connect Mailforge to an internal system, CRM, client onboarding flow, RevOps workflow, or custom provisioning tool.

What the Mailforge API is used for

You can use the Mailforge API to automate infrastructure-related tasks, including:

• Listing and creating workspaces

• Checking domain availability

• Checking domain availability in bulk

• Purchasing domains

• Listing domains

• Reviewing domain DNS records

• Updating DNS records

• Creating mailboxes

• Listing mailboxes

• Updating mailbox details

• Managing mailbox forwarding

• Managing domain forwarding

• Enabling or disabling domain auto-renewal

• Deleting mailboxes or workspaces when needed

The API is designed for Mailforge infrastructure management. It does not run Salesforge sequences, send campaigns, manage Primebox replies, or control LinkedIn steps.

Base URL

The Mailforge public API uses the following base URL:

https://api.mailforge.ai/public

All public API requests should be made against this base URL, followed by the endpoint you want to use.

For example:

GET /workspaces

becomes:

https://api.mailforge.ai/public/workspaces

How to create a Mailforge API key

To create an API key:

1. Log in to your Mailforge account.

2. Go to Settings.

3. Open the API section.

4. Create a new API key.

5. Copy and store the key securely.

Make sure you are using a Mailforge API key. API keys from other Forge products, such as Salesforge or Warmforge, should not be used for Mailforge API requests.

Authentication

For Mailforge public API requests, pass your Mailforge API key in the Authorization header.

Example:

curl --request GET \
  --url "https://api.mailforge.ai/public/workspaces" \
  --header "Authorization: YOUR_MAILFORGE_API_KEY" \
  --header "Accept: application/json"

A successful request will return the workspaces available to your account.

If this request fails, check that:

• The API key was created in Mailforge

• The key is being sent in the Authorization header

• The request is using the correct base URL

• The key has not been disabled or rotated

• The key is not being exposed from frontend/browser-side code

Recommended first API test

The best first test is to list your workspaces.

Use:

GET /workspaces

This confirms that your API key is valid and that your integration can access your Mailforge account.

Example:

curl --request GET \
  --url "https://api.mailforge.ai/public/workspaces" \
  --header "Authorization: YOUR_MAILFORGE_API_KEY" \
  --header "Accept: application/json"

If the request succeeds, you can continue building the rest of your workflow.

Main Mailforge API areas

Workspaces

Workspaces help organize Mailforge infrastructure by client, project, brand, or campaign setup.

Common workspace endpoints include:

GET /workspaces
POST /workspaces
DELETE /workspaces/{workspaceID}

Use workspaces when you want to separate infrastructure for different clients or outbound projects.

When creating a workspace through the API, store the returned workspace ID. You will need it for downstream actions such as domain purchases.

Domain availability

Before purchasing domains, you can check whether domains are available.

Common endpoints include:

GET /check-domain-availability
POST /check-domain-availability-bulk
POST /domains/alternative-domains

Use these endpoints to:

• Check if a domain is available

• Check multiple domains at once

• Find alternative domain options

• Review availability before purchasing

Bulk domain availability checks are useful when you want to generate multiple domain options and only purchase the approved ones.

Domains

Domain endpoints allow you to purchase, list, review, and manage domains inside Mailforge.

Common endpoints include:

POST /domains
GET /domains
GET /domains/{domainID}/dns
PUT /domains/{domainID}/dns
PUT /domains/bulk-dns
PATCH /domains/forwards
PUT /domains/{domainID}/enable-autorenew
PUT /domains/{domainID}/disable-autorenew

Use domain endpoints when you want to:

• Purchase approved domains

• View domains in your workspace

• Check DNS records

• Update DNS records

• Apply DNS changes in bulk

• Configure forwarding

• Manage auto-renewal

Domain purchases and renewal changes can affect billing, so they should be handled carefully.

Mailboxes

Mailbox endpoints allow you to create, list, update, forward, and delete mailboxes.

Common endpoints include:

POST /mailboxes
GET /mailboxes
PATCH /mailboxes/{mailboxID}
POST /mailboxes/bulk-forward
DELETE /mailboxes/{mailboxID}

Use mailbox endpoints when you want to:

• Create new mailboxes

• View existing mailboxes

• Update mailbox details

• Manage forwarding

• Retrieve mailbox information

• Delete mailboxes when needed

Mailbox creation should usually happen after the required domains are active.

Retrieving mailbox credentials

Mailbox endpoints may support retrieving credentials when needed.

Credentials can include sensitive mailbox access details such as SMTP and IMAP information.

Only retrieve credentials when required for your workflow, and never expose them in:

• Frontend code

• Browser-side scripts

• Public logs

• Shared spreadsheets

• Screenshots

• Slack messages

• Unsecured internal tools

If you are using Salesforge, the recommended flow is usually to connect or export mailboxes into Salesforge rather than manually handling credentials.

DNS management

Mailforge helps manage DNS for Mailforge-created infrastructure, including standard email authentication records.

You can use DNS endpoints to inspect or update DNS records when needed.

Common DNS actions include:

• Viewing current DNS records

• Adding custom records

• Updating editable records

• Applying DNS changes in bulk

• Checking records before campaign activation

Before updating DNS through the API, always review the current records first.

Incorrect DNS changes can affect:

• Email authentication

• Mailbox sending

• Mailbox receiving

• Domain forwarding

• Tracking setup

• Deliverability

Forwarding

Forwarding endpoints help route replies and domain traffic correctly.

Mailforge supports both domain forwarding and mailbox forwarding workflows.

Common forwarding endpoints include:

PATCH /domains/forwards
POST /mailboxes/bulk-forward

Use forwarding when you want replies or domain traffic to be routed to a specific destination.

After making forwarding changes, confirm the forwarding status before relying on it in production workflows.

Domain and mailbox statuses

Your API workflow should check status before moving to the next step.

A domain or mailbox should not be treated as ready just because the creation request was submitted.

Common domain statuses can include:

• Draft

• Pending

• Active

• Failed

• Expired

• Scheduled for deletion

• Not paid

Common mailbox statuses can include:

• Draft

• Pending

• Processing

• Active

• Failed

• Scheduled for deletion

Before using mailboxes in campaigns, check that the required domains and mailboxes are active.

Common API response codes

The Mailforge API may return different response codes depending on the request.

Common examples include:

Code

Meaning

A 202 Accepted response means the request has been accepted for processing. It does not always mean the operation is fully complete. For bulk or async actions, re-check the resource later to confirm the final status.

Recommended provisioning workflow

A common Mailforge API workflow looks like this:

1. Create or select the correct workspace.

2. Check domain availability.

3. Review and approve the domains to purchase.

4. Purchase the approved domains.

5. Store the returned domain IDs.

6. Wait for domains to become active.

7. Create mailboxes on the active domains.

8. Wait for mailboxes to become active.

9. Configure forwarding if needed.

10. Review DNS and mailbox status.

11. Connect the mailboxes to your sending workflow.

12. Start warm-up before live sending.

The API can automate the setup, but campaign sending should only begin once the infrastructure is ready.

What should be automated carefully

Some API actions are low-risk and safe to automate early.

Examples:

• Listing workspaces

• Checking domain availability

• Listing domains

• Listing mailboxes

• Reading DNS records

Other actions should have approval or additional checks before being automated.

Examples:

• Purchasing domains

• Updating DNS records

• Bulk DNS updates

• Changing forwarding

• Enabling or disabling auto-renewal

• Deleting mailboxes

• Deleting workspaces

These actions can affect infrastructure, billing, or deliverability, so they should be protected with review steps.

Security best practices

When using the Mailforge API:

• Store API keys securely

• Keep API keys server-side only

• Do not expose API keys in frontend code

• Do not commit keys to GitHub

• Use environment variables or a secrets manager

• Rotate keys if they are exposed

• Limit access to tools that can purchase, delete, or update DNS

• Log actions without logging sensitive credentials

• Add approval steps for financial or destructive actions

Treat your Mailforge API key as production infrastructure access.

Summary

The Mailforge API helps you automate email infrastructure workflows such as workspace creation, domain availability checks, domain purchases, mailbox creation, DNS management, forwarding, and mailbox management.

Use the API for infrastructure provisioning and management. Use Salesforge for campaign sending, sequencing, and reply management.

Start with read-only actions such as listing workspaces and checking domain availability. Then add guarded write actions such as workspace creation, approved domain purchases, mailbox creation, DNS updates, and forwarding changes.

Always store API keys securely, verify resource statuses, and avoid sending campaigns until the domains and mailboxes are active and properly warmed.