Inbox and calendar · 7 min
Send Email to Your Workspace with a Custom Integration
Custom email integrations let another system push messages directly into your workspace Mail page. Use the Mailbox setup panel to copy the API URL, generate a Bearer token, and send JSON payloads from your integration.
Walkthrough
Step by step
Open the Mail page
Sign in to VZFLO and open Mail from the app navigation. This page shows messages received by forwarding and custom email integrations.
Mailbox
Workspace Mail
Customer emails received by this workspace inbox and API integrations.
Open Mail, then use Configure to find custom integration settings.
If Mail is not visible, the workspace mail feature may not be enabled for that organization yet.
Open Mailbox setup
Click Configure in the Mail page header. The setup panel shows the workspace inbox address and, when enabled, custom integration settings.
Mailbox setup
Custom integrations
Send email records directly to this workspace mailbox from another system.
The setup panel shows the API URL and the API key controls when custom integrations are enabled.
Custom API access is only shown for workspaces that have custom email integrations enabled.
Copy the Mailbox ingest endpoint
Copy the Mailbox ingest endpoint from the setup panel. This is the API URL your integration posts email records to.
POST /api/integrations/custom-email/messages Authorization: Bearer YOUR_VZMAIL_KEY Content-Type: application/json
Copy this endpoint exactly. Your integration sends one POST request per email record.
The production endpoint is usually https://www.vzflo.com/api/integrations/custom-email/messages.
Generate an API key
Under API keys, enter a key name such as Gmail Sync, Zapier Forwarder, or Custom Email Integration, then choose Generate key.
The full key is shown once. Store it securely and use it as the Bearer token.
The full key is shown once. Store it in your integration secret manager and use it as the Bearer token.
Post email JSON to the endpoint
Send a POST request with Authorization: Bearer YOUR_KEY and a JSON body that includes sender, recipients, subject, body text, received time, labels, and optional raw metadata.
curl -X POST "https://www.vzflo.com/api/integrations/custom-email/messages" \
-H "Authorization: Bearer YOUR_VZMAIL_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_message_id": "gmail-message-id",
"thread_id": "gmail-thread-id",
"from": "lead@example.com",
"from_name": "Lead Example",
"to": ["owner@example.com"],
"subject": "Need a quote",
"text_body": "Can you send pricing?",
"received_at": "2026-05-18T20:10:00Z",
"labels": ["gmail", "lead"],
"raw": {}
}'
Include the Bearer key, JSON content type, and a stable external message id from the source system.
Use a stable external_message_id from the source system so retries do not create duplicate messages.
Confirm the message appears
Return to Mail and confirm the message appears in the Messages table with source custom_email. Workspace agents with Mailbox messages access can read it later.
After a successful POST, the message appears in Mail and can trigger Email received workspace agents.
If you use the Email received trigger, workspace agents can run automatically when a new custom integration message is created.
Before you finish
Launch checklist
- Custom email integrations are enabled for the workspace.
- The Mailbox ingest endpoint was copied from Mailbox setup.
- An API key was generated and stored securely.
- The integration sends Authorization: Bearer YOUR_KEY.
- The JSON payload includes a sender, subject, body, and received_at timestamp when available.
- A test message appears on the Mail page.
Fix common issues
Troubleshooting
The setup panel does not show API keys.
Custom email integrations may not be enabled for that workspace. Enable the feature for the organization, then reopen Mailbox setup.
The API returns 401.
Confirm the request uses Authorization: Bearer followed by the full generated key. If the key was lost, generate a new one.
The API returns 403.
Custom email integration is not enabled for the workspace associated with that key.
The message posts successfully but an agent does not react.
Confirm the workspace agent has the Email received trigger enabled and Mailbox messages read access.
Keep learning