Doc for API - MailboxAPI

Authentication

This API does not require authentication.

Email

/sendemail/ • Methods: POST

Send email

Send an email using a selected SMTP box (apikey/apikeybox). Supports HTML or text content, CCs, base64 attachments, inline images (CID), and unsubscribe footer.

POST /sendemail/ • Rate: 120 req/min • Auth required

Parameters

Name	Type	Required	Default	Description
`apikey`	string	Yes		Your MailBridge API key (supports Authorization: Bearer or apikey param).
`apikeybox`	string	Yes		SMTP box key to use (email_box.api_key).
`recipient_email`	string	Yes		Primary recipient email address.
`mail_subject`	string	Yes		Email subject.
`mail_body`	string	Yes		Email body (HTML by default unless format=text).
`sender_email`	string	No		Override From email (defaults to SMTP box sender).
`sender_name`	string	No		Override From name (defaults to SMTP box sender).
`reply_email`	string	No		Reply-To email (defaults to sender_email).
`reply_name`	string	No		Reply-To display name.
`email_cc1`	string	No		Optional CC #1.
`email_cc2`	string	No		Optional CC #2.
`email_cc3`	string	No		Optional CC #3.
`format`	string	No	html	"html" (default) or "text".
`charset`	string	No	UTF-8	Character set for the message.
`allow_self_signed`	string	No		Set "yes" to allow self-signed TLS certificates.
`attachmentBase64_1`	string	No		Attachment #1 content (base64).
`attachmentBase64_name_1`	string	No		Attachment #1 filename.
`attachmentBase64_2`	string	No		Attachment #2 content (base64).
`attachmentBase64_name_2`	string	No		Attachment #2 filename.
`embeddedImage`	string	No		Public image URL to embed inline.
`embeddedImage_cid`	string	No		CID used in HTML body (e.g., <img src="cid:YOUR_CID">).
`unsubscribe`	string	No	0	"1" to append unsubscribe footer.
`from_source`	string	No		Optional source tag for analytics (e.g., "api","app").

Request examples

CURL

JAVASCRIPT

PYTHON

curl -X POST "https://api.mailbridgeapi.com/sendemail/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "apikey=YOUR_API_KEY" \ -d "apikeybox=YOUR_SMTP_BOX_KEY" \ -d "recipient_email=user@example.com" \ -d "sender_email=noreply@example.com" \ -d "sender_name=Marketing" \ -d "mail_subject=Hello" \ -d "mail_body=Hi there!"

curl -X POST "https://api.mailbridgeapi.com/sendemail/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "apikey=YOUR_API_KEY" \ -d "apikeybox=YOUR_SMTP_BOX_KEY" \ -d "recipient_email=user@example.com" \ -d "mail_subject=Invoice" \ -d "mail_body=Please find attached" \ -d "email_cc1=finance@example.com" \ -d "attachmentBase64_1=$(base64 -w0 invoice.pdf)" \ -d "attachmentBase64_name_1=invoice.pdf"

fetch("https://api.mailbridgeapi.com/sendemail/", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ apikey: "YOUR_API_KEY", apikeybox: "YOUR_SMTP_BOX_KEY", recipient_email: "user@example.com", sender_email: "noreply@example.com", sender_name: "Marketing", mail_subject: "Hello", mail_body: "Hi there!", format: "html" }) }).then(r => r.json()).then(console.log);

import requests\nr = requests.post("https://api.mailbridgeapi.com/sendemail/", json={\n "apikey":"YOUR_API_KEY",\n "apikeybox":"YOUR_SMTP_BOX_KEY",\n "recipient_email":"user@example.com",\n "sender_email":"noreply@example.com",\n "sender_name":"Marketing",\n "mail_subject":"Hello",\n "mail_body":"Hi there!",\n "format":"html"\n})\nprint(r.json())

Responses

Status: 200 — SMTP result is returned in the payload (success or error).

JSON

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

Status: 400 — Missing required parameters (apikey/apikeybox/recipient/subject/body).

Status: 401 — Invalid/expired API key or deactivated for spam.

Status: 500 — SMTP/provider error or internal failure.

/email/unsubscribed/ • Methods: GET

List unsubscribed emails

Returns the last (max 500) email sends that asked to unsubscribe (unsubscribe=1 and unsubscribe_asked=1) for the given API key and SMTP box. Optional filter by recipient email.

GET /email/unsubscribed/ • Rate: 120 req/min • Auth required

Parameters

Name	In	Type	Required	Description
`apikey`		string	Yes	Your MailBridge API key. Supports Authorization: Bearer or apikey query param.
`apikeybox`	query	string	Yes	SMTP box key (email_box.api_key).
`email`	query	string	No	Optional filter: only records for this recipient email.
`start`	query	integer	No	Optional start index (reserved; may be ignored by current implementation).

Request examples

CURL

JAVASCRIPT

PYTHON

curl "https://api.mailbridgeapi.com/email/unsubscribed/?apikey=YOUR_API_KEY&apikeybox=YOUR_SMTP_BOX_KEY"

curl "https://api.mailbridgeapi.com/email/unsubscribed/?apikey=YOUR_API_KEY&apikeybox=YOUR_SMTP_BOX_KEY&email=user@example.com"

fetch("https://api.mailbridgeapi.com/email/unsubscribed/?apikey=YOUR_API_KEY&apikeybox=YOUR_SMTP_BOX_KEY&email=user@example.com") .then(r => r.json()) .then(console.log);

import requests\nr = requests.get("https://api.mailbridgeapi.com/email/unsubscribed/", params={\n "apikey":"YOUR_API_KEY",\n "apikeybox":"YOUR_SMTP_BOX_KEY",\n "email":"user@example.com"\n})\nprint(r.json())

Responses

Status: 200 — Success — returns an array of unsubscribed send logs under result.customer.

JSON

{ "result": { "error": "0", "customer": [ { "dateSent": "2025-01-10", "hourSent": "14:22:05", "guidMessage": "6f0c2b9e6a0d...f3", "senderName": "Marketing", "senderEmail": "noreply@example.com", "recipientEmail": "user@example.com", "subject": "Monthly newsletter", "body": "Hi!", "unsubscribeaskedDate": "2025-01-11", "unsubscribeaskeHour": "08:15:30" } ] } }

Status: 400 — Missing required parameters (apikey/apikeybox).

Status: 401 — Invalid/expired API key or deactivated.

Status: 500 — Server/DB error.

/getemail • Methods: GET

Fetch emails from an IMAP mailbox

Connects to the IMAP box linked to the given apikeybox and returns messages (UID-keyed map) from the selected folder. Supports pagination via start (30 messages per page).

GET /getemail • Rate: 60 req/min • Auth required

Parameters

Name	In	Type	Required	Default	Description
`apikey`		string	Yes		Your MailBridge API key. Supports Authorization: Bearer or apikey query param.
`apikeybox`	query	string	Yes		SMTP/IMAP box key (email_box.api_key) to use for connection.
`mbox`	query	string	Yes		IMAP folder name to read from (e.g. INBOX, Sent, Drafts).
`start`	query	integer	No	0	Zero-based start index for paging. The API returns up to 30 messages from this index.

Request examples

CURL

JAVASCRIPT

PYTHON

curl "https://api.mailbridgeapi.com/getemail?apikey=YOUR_API_KEY&apikeybox=YOUR_BOX_KEY&mbox=INBOX&start=0"

curl "https://api.mailbridgeapi.com/getemail?apikey=YOUR_API_KEY&apikeybox=YOUR_BOX_KEY&mbox=INBOX&start=30"

fetch("https://api.mailbridgeapi.com/getemail?apikey=YOUR_API_KEY&apikeybox=YOUR_BOX_KEY&mbox=INBOX&start=0") .then(r => r.json()) .then(console.log);

import requests\nurl = "https://api.mailbridgeapi.com/getemail"\nparams = {\n "apikey": "YOUR_API_KEY",\n "apikeybox": "YOUR_BOX_KEY",\n "mbox": "INBOX",\n "start": 0\n}\nprint(requests.get(url, params=params).json())

Responses

Status: 200 — Success — returns a UID-keyed object of emails under result.emaillist.

JSON

{ "result": { "error": "0", "emaillist": { "50123": { "id": 50123, "object": "Welcome%20to%20MailBridge", "body": "%3Cp%3EHello%20there%3C%2Fp%3E", "email1": "sender@example.com", "email2": "me@example.com", "timestamp": 1736505600, "date": "10/01/2025 - 09:20:00", "size": 42, "attachment": null, "loop": 0 }, "50124": { "id": 50124, "object": "Invoice%20Jan", "body": "%3Cp%3EInvoice%20attached%3C%2Fp%3E", "email1": "billing@example.com", "email2": "me@example.com", "timestamp": 1736510000, "date": "10/01/2025 - 10:33:20", "size": 138, "attachment": "invoice-jan.pdf", "loop": 1 } } } }

Status: 400 — Missing required parameters (apikey/apikeybox/mbox).

Status: 401 — Invalid/expired API key or deactivated.

Status: 500 — Server/IMAP error.

Webhooks

No webhooks documented.

SDKs

No SDKs listed.

Error catalog

No errors defined.

Changelog

No releases yet.