Gateway API Reference
FulcrumSend Mail Gateway API
Use these endpoints to connect OpsHub first and later any approved external app. The gateway remains infrastructure-only while OpsHub remains the user-facing mail experience.
Base URLhttps://api.fulcrumsend.com
AuthInternal key
Send modeMailbox SMTP V2.13
ReceivingInbound MIME
Authentication headers
X-FulcrumSend-Key: YOUR_FS_INTERNAL_API_KEY
Content-Type: application/json
Never put the internal key inside public browser JavaScript. OpsHub backend/server actions must call the gateway.
Send Email API
This is the main endpoint OpsHub should use when sending task notifications, lead emails, form responses, invoices, huddle notices and system alerts.
POSThttps://api.fulcrumsend.com/gateway.php?action=message.send
Required fields
| Field | Required | Description |
|---|---|---|
| tenant_id | Yes | The OpsHub tenant/workspace owner of the mailbox. |
| mailbox_id | Yes | The gateway mailbox ID returned when the client mailbox was registered. |
| to | Yes | Recipient email address. |
| subject | Yes | Email subject line. |
| text or html | Yes | Provide plain text, HTML, or both. Plain text is used as fallback. |
| idempotency_key | Yes | Unique send key from OpsHub to stop accidental duplicate sends. |
Optional fields
| Field | Required | Description |
|---|---|---|
| signature_html | No | Email signature HTML appended to the message. |
| attachments | No | Array of base64 attachments with filename and content_type. |
| metadata | No | OpsHub module/object data for linking logs back to tasks, leads, invoices, bookings, tickets, etc. |
Request example
POST https://api.fulcrumsend.com/gateway.php?action=message.send
X-FulcrumSend-Key: YOUR_FS_INTERNAL_API_KEY
Content-Type: application/json
{
"tenant_id": "tenant_pristine_works",
"mailbox_id": 4,
"to": "customer@example.com",
"subject": "Your booking confirmation",
"text": "Your booking has been confirmed.",
"html": "<p>Your booking has been confirmed.</p>",
"signature_html": "<strong>Pristine Works</strong><br>Laundry and garment care",
"attachments": [
{
"filename": "quote.pdf",
"content_type": "application/pdf",
"content_base64": "BASE64_CONTENT"
}
],
"idempotency_key": "booking_123_confirmation_v1",
"metadata": {
"source": "opshub",
"module": "bookings",
"object_id": "booking_123"
}
}
Success response example
{
"ok": true,
"message_id": 18,
"status": "sent",
"tenant_id": "tenant_pristine_works",
"mailbox_id": 4
}
Error response examples
{
"ok": false,
"error": "Mailbox is not active"
}
{
"ok": false,
"error": "Mailbox does not belong to tenant"
}
{
"ok": false,
"error": "Recipient is suppressed"
}
OpsHub must create a fresh idempotency key per intended send, for example invoice_123_send_v1. Reusing the same key should not send the same email twice.
Endpoint list
| Action | Method | Endpoint | Purpose |
|---|---|---|---|
| Health | GET | /gateway.php?action=health | Check gateway availability. |
| Register mailbox | POST | /gateway.php?action=mailbox.register | Create a tenant-owned mailbox connection. |
| Test mailbox | POST | /gateway.php?action=mailbox.test | SMTP login test and activation. |
| Mailbox health | GET | /gateway.php?action=mailbox.health&tenant_id=TENANT_ID&mailbox_id=ID | Return activation and health status for a mailbox. |
| List mailboxes | GET | /gateway.php?action=mailbox.list&tenant_id=TENANT_ID | Return tenant mailbox connections. |
| Disconnect mailbox | POST | /gateway.php?action=mailbox.disconnect | Disable a mailbox connection. |
| Send message | POST | /gateway.php?action=message.send | Send using a tenant-owned mailbox. |
| Message logs | GET | /gateway.php?action=message.logs&tenant_id=TENANT_ID | Fetch outbound logs for OpsHub sync. |
| Inbound logs | GET | /gateway.php?action=inbound.logs&tenant_id=TENANT_ID | Fetch received-message logs. |
Register Mailbox API
Use this when a tenant/client connects a new email address inside OpsHub.
POSThttps://api.fulcrumsend.com/gateway.php?action=mailbox.register
{
"tenant_id": "tenant_pristine_works",
"opshub_workspace_id": "workspace_001",
"opshub_user_id": "user_001",
"email": "support@clientdomain.com",
"display_name": "Client Support",
"provider_type": "cpanel",
"smtp_host": "mail.clientdomain.com",
"smtp_port": 465,
"smtp_encryption": "ssl",
"smtp_username": "support@clientdomain.com",
"smtp_password": "MAILBOX_PASSWORD",
"imap_host": "mail.clientdomain.com",
"imap_port": 993,
"imap_encryption": "ssl",
"imap_username": "support@clientdomain.com",
"imap_password": "MAILBOX_PASSWORD",
"test_now": true
}
Inbound Receiving APIs
Use these for incoming mail, reply capture and future OpsHub message sync.
HTTP inbound
POST https://inbound.fulcrumsend.com/gateway-inbound-v26.php
X-FulcrumSend-Key: YOUR_FS_INTERNAL_API_KEY
Content-Type: application/json
{
"raw_mime": "FULL_RAW_EMAIL_SOURCE",
"tenant_id": "tenant_pristine_works",
"mailbox_id": 4,
"forwarding_address": "support.tenant.a1b2@inbound.fulcrumsend.com"
}
cPanel pipe
/home/fulcrumbiz2/public_html/inbound.fulcrumsend.com/gateway-pipe-v26.php
Use this as the forwarder pipe path when receiving raw inbound email directly from cPanel.
Copy-ready OpsHub JavaScript
async function sendEmailThroughFulcrumSend(payload) {
const response = await fetch('https://api.fulcrumsend.com/gateway.php?action=message.send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-FulcrumSend-Key': process.env.FULCRUMSEND_INTERNAL_API_KEY
},
body: JSON.stringify(payload)
});
const data = await response.json();
if (!response.ok || !data.ok) {
throw new Error(data.error || 'FulcrumSend send failed');
}
return data;
}
Do not expose FULCRUMSEND_INTERNAL_API_KEY in public frontend code. It must only run in OpsHub backend/server actions.