Mailboxes API

REST endpoints for mailboxes in ServFlo: 5 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
My connected mailbox	`GET /organizations/{organizationId}/mailboxes/me`	`read`
Send from my mailbox or my ServFlo address	`PATCH /organizations/{organizationId}/mailboxes/me`	`write`
Disconnect my mailbox	`DELETE /organizations/{organizationId}/mailboxes/me`	`sensitive`
Connect my Gmail or Outlook	`POST /organizations/{organizationId}/mailboxes/me/connect`	`sensitive`
Check my mailbox now	`POST /organizations/{organizationId}/mailboxes/me/sync`	`write`

My connected mailbox

GET /organizations/{organizationId}/mailboxes/me

The signed-in person's connected Gmail or Outlook (null when none) and which of the two this server can connect. Read-only.

Permission: inbox.reply (Owner, Admin, Dispatcher, Technician (own jobs)); risk read (OAuth scope servflo.read).


Permission	`inbox.reply`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`mailboxes_mine` (toolset `marketing`)

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/mailboxes/me" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`mailbox`	object or null
`mailbox.provider`	enum	One of `GMAIL`, `OUTLOOK`.
`mailbox.address`	string
`mailbox.status`	enum	One of `CONNECTED`, `ERROR`, `DISCONNECTED`.
`mailbox.sendFromMailbox`	boolean	Their Inbox emails go out through this mailbox (else their ServFlo address).
`mailbox.lastSyncAt`	string (date-time) or null
`mailbox.lastError`	string or null
`mailbox.fake`	boolean
`providers`	array of object
`providers[].provider`	enum	One of `GMAIL`, `OUTLOOK`.
`providers[].available`	boolean
`providers[].reason`	string or null

Send from my mailbox or my ServFlo address

PATCH /organizations/{organizationId}/mailboxes/me

Whether the signed-in person's Inbox emails go out through their connected mailbox (their real address) or their ServFlo address.

Permission: inbox.reply (Owner, Admin, Dispatcher, Technician (own jobs)); risk write (OAuth scope servflo.write).


Permission	`inbox.reply`
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`mailboxes_setSending` (toolset `marketing`)

Request body

Field	Type	Required	Description
`sendFromMailbox`	boolean	Yes

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/mailboxes/me" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sendFromMailbox":true}'

Response

200: the answer's fields

Field	Type	Description
`provider`	enum	One of `GMAIL`, `OUTLOOK`.
`address`	string
`status`	enum	One of `CONNECTED`, `ERROR`, `DISCONNECTED`.
`sendFromMailbox`	boolean	Their Inbox emails go out through this mailbox (else their ServFlo address).
`lastSyncAt`	string (date-time) or null
`lastError`	string or null
`fake`	boolean

Disconnect my mailbox

DELETE /organizations/{organizationId}/mailboxes/me

Stops using the signed-in person's connected mailbox and forgets its tokens; what already came into the Inbox stays.

Permission: inbox.reply (Owner, Admin, Dispatcher, Technician (own jobs)); risk sensitive (OAuth scope servflo.sensitive).


Permission	`inbox.reply`
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`mailboxes_disconnect` (toolset `marketing`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/mailboxes/me" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`disconnected`	boolean

Connect my Gmail or Outlook

POST /organizations/{organizationId}/mailboxes/me/connect

Starts connecting the signed-in person's own mailbox: answers Google's or Microsoft's consent page (authorizeUrl) for the person to open. Once connected, their mail with customers comes into the Inbox and their Inbox emails go out through it. Nothing changes until they allow it.

Permission: inbox.reply (Owner, Admin, Dispatcher, Technician (own jobs)); risk sensitive (OAuth scope servflo.sensitive).


Permission	`inbox.reply`
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`mailboxes_connect` (toolset `marketing`)
Approval	Waits for your approval in ServFlo when called with an API key or a connected app: the first call answers `428 APPROVAL_REQUIRED`; once you approve it, repeat the call with the `X-ServFlo-Approval` header. See Approvals.

Request body

Field	Type	Required	Description
`provider`	enum	Yes	One of `GMAIL`, `OUTLOOK`.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/mailboxes/me/connect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"GMAIL"}'

Response

200: the answer's fields

Field	Type	Description
`authorizeUrl`	string
`mode`	enum	One of `live`, `fake`.

Check my mailbox now

POST /organizations/{organizationId}/mailboxes/me/sync

Brings in the signed-in person's new mail with customers now, instead of waiting for the next check (every few minutes). Only email with a customer's address, or continuing an Inbox thread, comes in.

Permission: inbox.reply (Owner, Admin, Dispatcher, Technician (own jobs)); risk write (OAuth scope servflo.write).


Permission	`inbox.reply`
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`mailboxes_sync` (toolset `marketing`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/mailboxes/me/sync" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`imported`	integer
`skipped`	integer

On this page