MAILBRIDGEAPI / DOCUMENTATION

Email API documentation: SMTP and IMAP.

Connect your own SMTP and IMAP mailbox to an account API key and a mailbox API key. Use both in HTTP requests to send from, read, and manage that selected mailbox.

Base URLhttps://api.mailbridgeapi.com

Follow API and product changes.

Review published endpoint, documentation and platform updates before changing an integration.

Open the changelog

Building with an AI assistant?

Use our searchable knowledge base, full text reference, and read-only API to give your assistant source-backed MailBridgeAPI documentation.

Explore the knowledge base

Your first request, in three steps

Start by reading your inbox. Once you see a successful response, you can try sending a message.

Connect your keys

Paste your account API key and the key for one configured mailbox. Click Connect.

Fetch your inbox

Open “Retrieve emails”, keep INBOX and start 0, then click Fetch emails.

Read the result

HTTP 200 means the server replied. result.error = "0" indicates success; emails are inside result.emaillist.

SEE THE CONNECTION

One mailbox becomes an API your projects can use.

MailBridgeAPI securely links your SMTP and IMAP mailbox to two API keys. Your applications then call clear endpoints to send email and process received messages without using the mailbox password.

01Your mailboxyou@company.comYour address and provider

MailBridgeAPI

Mailbox API keymbox_••••7F3A

Linked and ready

03Callable endpoints

POST /sendemail/

GET /getemail/

GET /email/unsubscribed/

04Your projects

WebsiteCRMAutomation

Your project keeps the API keys on its server. The mailbox password stays in the MailBridgeAPI configuration.

INTERACTIVE API EXPLORER Not connected

Try the API with your mailbox

Connect your account key, choose a mailbox, then run a request below. These requests use the live MailBridgeAPI service.

Keys stay in this page’s memory and are cleared on disconnect or reload. Requests pass through this website’s server to MailBridgeAPI.

MORE THAN SEND AND RECEIVE

Professional endpoints for operating your mailbox.

Inspect readiness, review activity, find a specific message, build reporting and validate a send before it reaches SMTP. Every endpoint uses the same account and mailbox keys.

Use headers for new integrations

Send the account key in X-API-Key and the selected mailbox key in X-Mailbox-Key. Query parameters apikey and apikeybox remain available for compatibility. Keep both values on your server.

X-API-KeyX-Mailbox-Key

GET/mailbox/status/

Mailbox readiness

Check that SMTP and IMAP are configured and see which mailbox features are ready, without exposing usernames or passwords.

Use it for setup screens, monitoring and support diagnostics.

Useful parametersNo additional parameters.

Request example+

<?php
$params = [

];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/mailbox/status/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/email/sent/

Sent email history

Retrieve a paginated log of emails sent through this mailbox, with filters for status, recipient, date and source.

Build delivery dashboards and quickly identify SMTP errors.

Useful parameters

pageper_pagestatusrecipientfromtosourceinclude_body

Request example+

<?php
$params = [
    'page' => '1',
    'per_page' => '5',
    'status' => 'all',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/email/sent/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/email/received/

Received email history

Read the messages already stored by MailBridgeAPI with pagination and sender or date filters.

Feed support tools, CRM timelines and processing queues.

Useful parameters

pageper_pagesenderfromtoinclude_body

Request example+

<?php
$params = [
    'page' => '1',
    'per_page' => '5',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/email/received/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/email/message/

Message detail

Retrieve one sent or received message using its MailBridgeAPI message id.

Open a complete message only when a user selects it.

Useful parameters

directionid

Request example+

<?php
$params = [
    'direction' => 'sent',
    'id' => '',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/email/message/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/email/activity/

Mailbox activity

Get sent, accepted, error and received totals plus a daily series for 1 to 90 days.

Power charts, health checks and operational reporting.

Useful parameters

days

Request example+

<?php
$params = [
    'days' => '30',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/email/activity/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

POST/email/validate/

Send preflight validation

Validate recipient, subject, body, format and SMTP readiness without sending an email.

Catch integration mistakes before calling /sendemail/.

Useful parameters

recipient_emailmail_subjectmail_bodyformat

Request example+

<?php
$payload = [
    'recipient_email' => 'developer@example.com',
    'mail_subject' => 'Preflight validation',
    'mail_body' => 'This payload is validated without sending an email.',
    'format' => 'text',
];

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];
$headers[] = 'Content-Type: application/json';

$ch = curl_init('https://api.mailbridgeapi.com/email/validate/');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/mailbox/insights/

Mailbox insights

Get delivery reliability, received volume, recent activity and the latest error in one operational snapshot.

Power status pages, alerts and customer-facing health screens.

Useful parameters

days

Request example+

<?php
$params = [
    'days' => '30',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/mailbox/insights/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

GET/email/search/

Unified email search

Search sent and received metadata by message id, subject or email address, without loading message bodies.

Find a conversation quickly across both directions.

Useful parameters

querydirectionpageper_pagefromto

Request example+

<?php
$params = [
    'query' => 'invoice',
    'direction' => 'all',
    'page' => '1',
    'per_page' => '10',
];
$query = http_build_query($params);
$url = 'https://api.mailbridgeapi.com/email/search/' . ($query === '' ? '' : '?' . $query);

$headers = [
    'X-API-Key: ' . getenv('MAILBRIDGE_API_KEY'),
    'X-Mailbox-Key: ' . getenv('MAILBRIDGE_BOX_KEY'),
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Test with your connected keysLIVE

Live JSON response

Run the endpoint to display its response.

Download OpenAPI 3.1 specificationImport the complete contract into Postman, Insomnia, Swagger UI or your code generator.

Choose what you want to do

Retrieve emails

Read up to 30 emails from an IMAP folder.

GET

Send an email

Send one email from your connected mailbox.

POST

Unsubscribe records

Read opt-out records to update your contact list.

GET

Two keys. Two different jobs.

Use both values on every request. Your email password is not used in API requests.

apikey

Account API key

Identifies your account. Find it in your MailBridgeAPI dashboard.

apikeybox

Mailbox API key

Selects the mailbox to send from or read. This is the apikeybox value in your dashboard.

Requests require two values: apikey identifies your account; apikeybox selects your connected mailbox. Every endpoint then acts on that selected mailbox. Keep both keys in server-side environment variables.

Authentication — Optional

For GET endpoints, query parameters can appear in logs. The published reference also describes Bearer authentication for the account key; verify support in your integration before adopting it.

GET/getemail/

Retrieve emails

Read messages from an IMAP folder in your mailbox selected by apikeybox. The result contains a UID-keyed map under result.emaillist. Each page contains up to 30 messages; increment start by 30 to retrieve the next page.

Try this endpointLIVE

Connect your account API key above to try this endpoint.

Go to API connection

Request preview

{
  "method": "GET",
  "url": "https://api.mailbridgeapi.com/getemail/",
  "parameters": {
    "apikey": "YOUR_CONNECTED_API_KEY",
    "apikeybox": "YOUR_SELECTED_MAILBOX_KEY",
    "mbox": "INBOX",
    "start": "0"
  }
}

Live response

Your response will appear here after you run the request.

Start with these parameters

Parameter	Required	Description
`apikey`	Required	Account API key.
`apikeybox`	Required	API key of the connected IMAP mailbox.
`mbox`	Required	IMAP folder name, such as INBOX, Sent, or Drafts.

All optional parameters+

Only add these when you need the corresponding feature.

Parameter	Required	Description
`start`	Optional	Zero-based index; defaults to 0. Up to 30 messages per page.

Request example

<?php
$query = http_build_query([
    'apikey' => getenv('MAILBRIDGE_API_KEY'),
    'apikeybox' => getenv('MAILBRIDGE_BOX_KEY'),
    'mbox' => 'INBOX',
    'start' => '0'
]);

$ch = curl_init('https://api.mailbridgeapi.com/getemail/?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Example only — no live requests

How to read this response

Messages are grouped by their IMAP UID under result.emaillist. Subject (object) and body may be URL-encoded. Decode those fields before displaying them as text.

An empty email list can be a valid successful response. Check the selected folder and start index.

Example response+

{
  "result": {
    "error": "0",
    "emaillist": {
      "50123": {
        "id": 50123,
        "object": "Hello%20there",
        "body": "%3Cp%3EHello%3C%2Fp%3E",
        "email1": "jane@example.com",
        "email2": "hello@yourcompany.com",
        "timestamp": 1736505600,
        "date": "10/01/2025 - 09:20:00",
        "size": 42,
        "attachment": null,
        "loop": 0
      }
    }
  }
}

POST/sendemail/

Send an email

Send an email through the SMTP connection of your mailbox selected by apikeybox. The request uses that mailbox as the sending connection and supports HTML, text, CC recipients, attachments, inline images, and an optional unsubscribe footer.

Optional Sent-folder archiving

Enable sent copies for the mailbox in the dashboard to archive successful API sends through a separate IMAP background job. SMTP sending remains independent: an IMAP problem cannot turn an accepted send into an API failure. Set skip_sent_copy=1 on any request that must never be archived.

Try this endpointLIVE

Connect your account API key above to try this endpoint.

Go to API connection

Request preview

{
  "method": "POST",
  "url": "https://api.mailbridgeapi.com/sendemail/",
  "parameters": {
    "apikey": "YOUR_CONNECTED_API_KEY",
    "apikeybox": "YOUR_SELECTED_MAILBOX_KEY",
    "mail_subject": "Hello from MailBridgeAPI",
    "mail_body": "This is a test email sent from my connected mailbox.",
    "format": "text"
  }
}

Live response

Your response will appear here after you run the request.

Start with these parameters

Parameter	Required	Description
`apikey`	Required	Account API key.
`apikeybox`	Required	API key of the SMTP mailbox to use.
`recipient_email`	Required	Primary recipient email address.
`mail_subject`	Required	Email subject.
`mail_body`	Required	HTML or plain text message body.

All optional parameters+

Only add these when you need the corresponding feature.

Parameter	Required	Description
`sender_email`	Optional	Override the sender address; defaults to the SMTP mailbox sender. Your provider must allow the address.
`sender_name`	Optional	Override the sender display name.
`reply_email`	Optional	Reply-To address; defaults to sender_email.
`reply_name`	Optional	Reply-To display name.
`email_cc1, email_cc2, email_cc3`	Optional	Up to three CC recipients.
`format`	Optional	html (default) or text.
`charset`	Optional	Message character set; defaults to UTF-8.
`attachmentBase64_1, attachmentBase64_2`	Optional	Attachment contents encoded as base64.
`attachmentBase64_name_1, attachmentBase64_name_2`	Optional	Filenames for the corresponding attachments.
`embeddedImage`	Optional	Public image URL to embed inline.
`embeddedImage_cid`	Optional	Content ID referenced in HTML using cid:YOUR_CID.
`unsubscribe`	Optional	Set to 1 to append the configured unsubscribe footer; default 0.
`from_source`	Optional	An optional source label for your send.
`skip_sent_copy`	Optional	Set to 1 to prevent this message from being copied to the configured IMAP Sent folder, even when sent-copy archiving is enabled.
`allow_self_signed`	Optional	Set to yes to allow self-signed TLS certificates. Omit for normal certificate validation.

Request example

<?php
$payload = [
    'apikey' => getenv('MAILBRIDGE_API_KEY'),
    'apikeybox' => getenv('MAILBRIDGE_BOX_KEY'),
    'recipient_email' => 'jane@example.com',
    'mail_subject' => 'Hello, possibilities.',
    'mail_body' => 'Your next idea starts here.',
    'format' => 'text',
];

$ch = curl_init('https://api.mailbridgeapi.com/sendemail/');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
// Check $data['result']['error'], not only the HTTP status.
print_r($data);

Example only — no live requests

How to read this response

Check result.error = "0" and result.sent = "OK". The SMTP server accepted the send; this does not guarantee delivery to the recipient’s inbox.

Example response+

{
  "result": {
    "error": "0",
    "sent": "OK",
    "id": "msg_example"
  }
}

GET/email/unsubscribed/

Unsubscribe records

Retrieve up to 500 unsubscribe-related send records for a mailbox under result.customer. Optionally filter by recipient email. The start parameter is reserved and may be ignored.

Try this endpointLIVE

Connect your account API key above to try this endpoint.

Go to API connection

Request preview

{
  "method": "GET",
  "url": "https://api.mailbridgeapi.com/email/unsubscribed/",
  "parameters": {
    "apikey": "YOUR_CONNECTED_API_KEY",
    "apikeybox": "YOUR_SELECTED_MAILBOX_KEY"
  }
}

Live response

Your response will appear here after you run the request.

Start with these parameters

Parameter	Required	Description
`apikey`	Required	Account API key.
`apikeybox`	Required	API key of the SMTP mailbox.

All optional parameters+

Only add these when you need the corresponding feature.

Parameter	Required	Description
`email`	Optional	Filter records by recipient email address.
`start`	Optional	Reserved index; may be ignored by the current implementation.

Request example

<?php
$query = http_build_query([
    'apikey' => getenv('MAILBRIDGE_API_KEY'),
    'apikeybox' => getenv('MAILBRIDGE_BOX_KEY'),
    'email' => 'jane@example.com'
]);

$ch = curl_init('https://api.mailbridgeapi.com/email/unsubscribed/?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
    $message = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($message);
}
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Example only — no live requests

How to read this response

Records are under result.customer. Use recipientEmail to update your list. This endpoint reads opt-out records; it does not unsubscribe a contact itself.

Example response+

{
  "result": {
    "error": "0",
    "customer": [
      {
        "recipientEmail": "jane@example.com",
        "subject": "Monthly update",
        "unsubscribeaskedDate": "2025-01-11"
      }
    ]
  }
}

Responses & errors

`200`	Request processed. Inspect result.error for the provider result.
`400`	Required parameters are missing.
`401`	Invalid or expired API key, or a deactivated account.
`500`	SMTP / IMAP provider failure or an internal error.

If something goes wrong

401 / invalid key+

Check both keys, the selected mailbox, and the account’s active status.

SMTP connection failure+

Check SMTP host, port, authentication, and sender permissions in the dashboard.

IMAP connection failure+

Check IMAP access, credentials, and the exact folder name.

No messages returned+

Try INBOX with start = 0. The folder may be empty.

Timeout after sending+

Check your dashboard or Sent folder before retrying. The send may already have happened.

Rate limits

Published limits: sending and unsubscribe retrieval — 120 requests/minute; IMAP retrieval — 60 requests/minute. Your provider’s own limits also apply. Handle failures and avoid retrying sends blindly, which can create duplicate emails.

Code samples are examples. Live requests run only when you explicitly submit an endpoint test.

Email API documentation: SMTP and IMAP.

Follow API and product changes.

Building with an AI assistant?

Your first request, in three steps

Connect your keys

Fetch your inbox

Read the result

One mailbox becomes an API your projects can use.

Try the API with your mailbox

Professional endpoints for operating your mailbox.

Use headers for new integrations

Mailbox readiness

Sent email history

Received email history

Message detail

Mailbox activity

Send preflight validation

Mailbox insights

Unified email search

Choose what you want to do

Two keys. Two different jobs.

Account API key

Mailbox API key

Retrieve emails

Start with these parameters

Request example

How to read this response

Send an email

Optional Sent-folder archiving

Start with these parameters

Request example

How to read this response

Unsubscribe records

Start with these parameters

Request example

How to read this response

Responses & errors

If something goes wrong

Rate limits

Connect your own mailbox to API keys, then control it through endpoints.

Send through your mailbox

Read your mailbox

Use your mailbox data