Inbox

Ta strona nie została jeszcze przetłumaczona na Twój język. Wyświetlamy wersję angielski (Wielka Brytania).

The Inbox API returns one ordered list of everyone waiting for an answer, your team chats and what arrived for you, and lets you clear rows and answer someone new before deciding whether they are a lead.

These endpoints take a signed-in member's session token (Authorization: Bearer <session-token>); API keys do not open them. See Authentication.

Base URL: https://api.fondaro.com. Every member can read their own Inbox. Writes (marking handled, dismissing, every POST and DELETE under /new-conversations) need an active plan.

Read the Inbox

GET /inbox

Returns one page of the Inbox, in order, for the person asking.

Parameter	In	Type	Required	Description
`view`	Query	`waiting` \| `new` \| `all`	No	The tab. Without it you get the list without team chats, `views` or `note`.
`scope`	Query	`me` \| `members` \| `agency`	No	Default `me`. Members always get `me`; `members` and `agency` are for admins.
`assigneeIds`	Query	string, repeatable	No	User ids for `scope=members`. Up to 100.
`channel`	Query	`email` \| `whatsapp` \| `linkedin` \| `instagram` \| `telegram`	No	Only rows on this channel.
`via`	Query	connected account id \| `team` \| `agencies`	No	Only rows from one inbox, your colleagues' chats, or other agencies.
`q`	Query	string	No	Rows whose name contains it. With a `view`, also matches `preview`. Up to 200 characters.
`cursor`	Query	string	No	`nextCursor` from the previous page. A cursor from another view starts from the top.
`limit`	Query	integer	No	1 to 50. Default 30.
`timeZone`	Query	IANA name	No	Used for "tomorrow" and "overnight". Default `UTC`.

bash

curl "https://api.fondaro.com/inbox?view=waiting&limit=30&timeZone=Europe/Madrid" \  -H "Authorization: Bearer $SESSION_TOKEN"

json

{  "asOf": "2026-09-25T10:00:00.000Z",  "scope": "me",  "items": [    {      "id": "message:6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11",      "kind": "awaiting_reply",      "group": "people",      "ref": { "kind": "lead", "id": "1042" },      "conversationKey": null,      "messageRef": { "kind": "message", "id": "6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11" },      "connectedAccountId": "3f0c6f8e-1c1a-4a7e-9e7b-2d0c7f6a1b11",      "occurredAt": "2026-09-25T08:58:12.000Z",      "lead": { "id": 1042, "firstName": "Lead", "lastName": "Example", "language": "en", "assigneeIds": ["user_2abc"] },      "title": "Lead Example",      "channel": "whatsapp",      "reason": { "code": "wrote", "channel": "whatsapp" },      "replyOwed": true,      "automatic": false,      "fromAnAgency": false,      "handleable": true,      "additionalCount": 0,      "offers": [],      "preview": "Hi! Is Saturday 11 still ok?",      "chat": null,      "faceUrl": "/inbox/faces/message/6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11",      "unread": true    }  ],  "nextCursor": null,  "groups": { "reconnect": 0, "people": 1, "team": 0, "invites": 0, "brochures": 0, "network": 0, "posts": 0 },  "counts": { "awaiting_reply": 1, "new_lead": 0 },  "waitingCount": 1,  "hasConnectedAccount": true,  "view": "waiting",  "views": { "waiting": 1, "new": 0 },  "note": null}

The item object

Field	Type	Description
`id`	string	The row's id. Used as `:ref` to dismiss a row with no message.
`kind`	string	What the row is (see Row kinds).
`group`	string	`reconnect`, `people`, `team`, `invites`, `brochures`, `network` or `posts`.
`ref`	object or null	What the row opens: `{ kind, id }` for a lead, `calendar_event`, `brochure`, `listing`, `organization`, `open_house` or chat `conversation`. `null` for `new_conversation` (use `conversationKey`) and `reconnect` (use `connectedAccountId`).
`conversationKey`	string or null	For `new_conversation`: the key for the new conversation endpoints.
`messageRef`	object or null	The message the row is about: `{ kind: "email" \| "message", id }`.
`connectedAccountId`	string or null	The inbox a message arrived on, or the inbox that needs reconnecting.
`occurredAt`	string	ISO 8601.
`lead`	object or null	`id`, `firstName`, `lastName`, `language`, `assigneeIds`.
`title`	string	The person, agency or chat name.
`channel`	string or null	`email`, `whatsapp`, `linkedin`, `instagram` or `telegram`.
`reason`	object	Why the row is here, as `{ code, ...parameters }` for your client to put into words.
`replyOwed`	boolean	The person is waiting for an answer.
`automatic`	boolean	An automatic message or a row a trigger created.
`fromAnAgency`	boolean	It came from another agency.
`handleable`	boolean	With a `view`: the row can be marked handled or dismissed.
`additionalCount`	integer	Other reasons this lead is here. A lead appears once, with its strongest reason.
`offers`	object[]	Ask Fondaro's suggestions for the message. Accepting one opens a proposal for the person to approve.
`preview`	string or null	The person's own words, about 140 characters at most. `null` when there are none.
`chat`	object or null	For team rows: conversation id, `type`, `scope` (`internal` or `external`), `waits`, `unreadCount`, `mentionCount`, `person`, `last`, `mentionedBy`.
`faceUrl`	string or null	Path of the person's profile picture (see Get a profile picture).
`unread`	boolean	Something new since you last opened this conversation. Yours alone.

groups, counts, waitingCount and views cover the whole Inbox, not the page and not the q, channel or via filter. note (first page of a view only) holds one or two server-chosen sentences as structured parts; it is null when there is nothing to say.

Row kinds

`kind`	A row when	It leaves when
`awaiting_reply`	The newest message on a lead, on any channel, is theirs	Anyone replies, a call connects, or it is marked handled
`new_conversation`	Someone who is not a lead wrote to one of your inboxes	Add as lead, link, Not a lead, or 14 days
`new_lead`	A lead assigned to you that nobody has contacted	Any call, sent email or message
`unassigned_lead`	A new lead with nobody on it (admins, `scope=agency`)	Someone is assigned
`invite_declined`	A lead declined or answered maybe to your upcoming meeting	The meeting moves, is cancelled or accepted
`brochure_opened`	Someone outside your agency opened a brochure you made for one lead	Any contact after the view, or 48 hours
`reconnect`	One of your inboxes needs reconnecting	It is connected again
`connect_request`	A member asked for an inbox the plan does not include (admins)	Allowed or declined
`connect_allowed`	An admin allowed the inbox you asked for	It connects
`co_listing_invitation`	Another agency invited you to co-list a home	Accepted or declined
`partnership_request`	Another agency asked to partner (admins)	Accepted or declined
`open_house_tomorrow`	Your open house is tomorrow and agents said they are going	The day passes
`agent_request`	An agent at another agency asked to message you	Accepted or declined
`request_reply`	Someone answered your buyer request in a chat	You reply, or the request closes
`post_draft`	A listing post waits for you: a draft, a failed post, or one whose account needs reconnecting	Published or discarded
`team_dm`	A direct message whose newest message is theirs and unread (with a `view`)	You read or reply
`team_mention`	An unread message in a channel or group mentions you (with a `view`)	You read it
`team_channel`	A channel or group that does not wait on you (`view=all` only)	Never waits
`lead_thread`	A lead's conversation that waits on nobody (`view=all` only)	Never waits

You only see chats you are a member of, at every scope; an admin's scope changes which leads show, never whose chats.

Views and order

`view`	What it holds
`waiting`	Every row that waits, waiting chats included
`new`	`new_lead`, `new_conversation`, `unassigned_lead` and `agent_request`
`all`	Every conversation, newest activity first, with requests to you pinned above the first page

In waiting and new, rows come in this order: a reconnect that blocks a reply, the people waiting (longest first), the team, declined invites, opened brochures, network rows, then post drafts. Ask Fondaro may lift or sink a row inside its group but never removes one. Paging is by position, so a row that clears between pages never shifts the next one.

Count who is waiting

GET /inbox/count

Returns the number on the Inbox icon: people waiting for you, one per lead, plus chats that owe you an answer and requests to you, always in your own scope.

bash

curl "https://api.fondaro.com/inbox/count" \  -H "Authorization: Bearer $SESSION_TOKEN"

json

{ "waitingCount": 3 }

Mark a conversation handled

POST /inbox/items/:ref/handled

Marks a message as needing no reply, or dismisses a row that has no message. DELETE on the same path undoes it.

Parameter	In	Type	Required	Description
`ref`	Path	string	Yes	URL-encoded. A message: `email:<uuid>`, `message:<uuid>`, or `lead:<id>` for the lead's newest message (which must be theirs). A row with no message: the row's `id`.
`timeZone`	Query	IANA name	No	Finds an open house "tomorrow" where you are. Default `UTC`.

A handled message holds on every device; the lead's next message is a new row. A dismissal holds for your whole organization until something newer happens on the row (another brochure view, a new answer to the invite), and you can only dismiss a row your Inbox shows you now. New conversations are decided with the new conversation endpoints, and chats clear when you read them.

bash

curl -X POST "https://api.fondaro.com/inbox/items/message%3A6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11/handled" \  -H "Authorization: Bearer $SESSION_TOKEN"

json

{  "messageRef": "message:6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11",  "handled": true,  "handledAt": "2026-09-25T10:02:41.000Z"}

Marking an already marked message keeps the first mark. DELETE returns "handled": false.

Mark many rows at once

POST /inbox/handled

Marks, dismisses or undoes up to 100 rows in one request, each by the rules above.

Parameter	In	Type	Required	Description
`refs`	Body	string[]	Yes	1 to 100 refs, each what `:ref` takes above.
`handled`	Body	boolean	Yes	`true` to mark or dismiss, `false` to undo.
`timeZone`	Body	IANA name	No	Default `UTC`.

A ref that no longer resolves is listed in failed; the rest still land.

bash

curl -X POST "https://api.fondaro.com/inbox/handled" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"refs": ["message:6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11", "new_lead:lead:1042"], "handled": true}'

json

{  "results": [    { "messageRef": "message:6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11", "handled": true, "handledAt": "2026-09-25T10:02:41.000Z" },    { "messageRef": "new_lead:lead:1042", "handled": true, "handledAt": "2026-09-25T10:02:41.000Z" }  ],  "failed": []}

Mark a conversation read

POST /inbox/read

Clears the row's unread dot for you alone. It does not clear a waiting row: that still waits until you answer or mark it handled. Needs no active plan.

Parameter	In	Type	Required	Description
`key`	Body	string	Yes	`lead:<id>` for any row of a lead, `conversation:<conversationKey>` for a new conversation, the row's `id` for anything else. Chats are read by reading them, not here.
`timeZone`	Body	IANA name	No	Default `UTC`.

bash

curl -X POST "https://api.fondaro.com/inbox/read" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"key": "lead:1042"}'

json

{ "key": "lead:1042", "readAt": "2026-09-25T10:02:41.000Z" }

Get a profile picture

GET /inbox/faces/:kind/:id

Returns the person's WhatsApp, Instagram, LinkedIn or Telegram profile picture as an image. Use the path in an item's faceUrl with your session token.

Parameter	In	Type	Required	Description
`kind`	Path	`message` \| `conversation`	Yes	A lead's chat message id, or a new conversation's key.
`id`	Path	string	Yes	The message id or conversation key.

bash

curl "https://api.fondaro.com/inbox/faces/message/6b0c9d0e-5d7a-4e0a-9d59-0f3c1e2a7b11" \  -H "Authorization: Bearer $SESSION_TOKEN" -o face.jpg

The image is cached privately for a day with an ETag. It answers 404 when the person has no picture or you cannot see the row.

Answer someone new

A new_conversation row is someone who wrote to one of your inboxes and is not a lead yet. Only the person who owns that inbox, or was given it by an admin, can open and answer it. :key is the row's conversationKey, URL-encoded. A conversation nobody decides on is deleted after 14 days (expiresAt).

Method and path	Purpose
`GET /new-conversations`	Your new conversations (`?channel=` narrows to one channel)
`GET /new-conversations/:key`	One conversation with its `messages`
`GET /new-conversations/:key/candidates`	Leads it might belong to, with `best` when one is a strong match
`POST /new-conversations/:key/reply`	Reply from the inbox they wrote to
`POST /new-conversations/:key/add-as-lead`	The lead details, prefilled from the messages. Writes nothing
`POST /new-conversations/:key/add-as-lead/confirm`	Create the lead and move the messages onto it
`POST /new-conversations/:key/link`	Move the messages onto an existing lead
`DELETE /new-conversations/:key`	Not a lead: the stored messages are deleted

Reply

POST /new-conversations/:key/reply

Sends from the inbox they wrote to. An email goes out as a reply to their newest message, so it stays in their thread; a chat message goes into their chat. The row stays until you decide, with replyOwed: false.

Parameter	In	Type	Required	Description
`body`	Body	string	Yes	Plain text, 1 to 20,000 characters. A chat message is at most 4,000.
`subject`	Body	string	No	Email only. Default: `Re:` and their newest subject.
`cc`	Body	string[]	No	Email only. Up to 10 addresses.
`bcc`	Body	string[]	No	Email only. Up to 10 addresses.
`bodyHtml`	Body	string	No	Email only. Formatted body, at most 100,000 characters, cleaned to basic text tags and http, https or mailto links before sending.

bash

curl -X POST "https://api.fondaro.com/new-conversations/email.3f0c6f8e-1c1a-4a7e-9e7b-2d0c7f6a1b11.YnV5ZXJAZXhhbXBsZS5jb20/reply" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"body": "Hello, the villa is free to view on Saturday at 11."}'

json

{  "message": {    "id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",    "kind": "email",    "direction": "outbound",    "subject": "Re: Villa in Mijas",    "body": "Hello, the villa is free to view on Saturday at 11.",    "messageAt": "2026-09-25T10:04:00.000Z",    "attachments": []  }}

Add as a lead

POST /new-conversations/:key/add-as-lead/confirm

Creates the lead (or matches an existing one with the same details) and moves the conversation onto it. Get prefilled values first with POST /new-conversations/:key/add-as-lead.

Parameter	In	Type	Required	Description
`firstName`	Body	string	Yes	Up to 100 characters.
`lastName`	Body	string	No	Up to 100 characters.
`email`	Body	string	No
`phoneNumber`	Body	string	No	Up to 50 characters.
`language`	Body	string	No	Language code.
`propertyListingId`	Body	uuid	No	One of your listings the person asked about.
`crmStatus`, `leadType`, `companyName`	Body	string	No	As on lead create.
`assigneeIds`, `teamIds`, `unassigned`	Body		No	Who owns the lead, as on lead create.

bash

curl -X POST "https://api.fondaro.com/new-conversations/email.3f0c6f8e-1c1a-4a7e-9e7b-2d0c7f6a1b11.YnV5ZXJAZXhhbXBsZS5jb20/add-as-lead/confirm" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"firstName": "Maria", "lastName": "Lopez", "email": "buyer@example.com"}'

json

{ "leadId": 1077, "created": true, "attachedEmails": 2, "attachedMessages": 0 }

POST /new-conversations/:key/link takes { "leadId": 1042 } and answers the same shape with created: false. DELETE /new-conversations/:key answers { "deletedEmails": 2, "deletedMessages": 0 }.

Live updates

When a message reaches a lead, a new conversation arrives or a row is marked, dismissed or brought back, the dashboard's chat socket sends inbox:changed (empty payload) to your organization; after POST /inbox/read it goes to your own sockets only. Refetch GET /inbox on it, and also every 60 seconds to cover a dropped socket.

From an MCP client

The MCP server tool list_inbox (scope crm:read) returns the Inbox as a read-only list. It never returns team chats, and there is no MCP tool to mark a row handled.

Errors

Status	Code	When
`400`		Invalid parameters, a `:ref` or `key` that is not a message, lead or dismissable row, an empty reply, or a chat reply over 4,000 characters
`403`	`SUBSCRIPTION_REQUIRED`	A write without an active plan
`403`	`SANDBOX_OUTBOUND_DISABLED`	A reply from a sandbox organization
`404`		No such message, row, lead or conversation that you can see
`409`	`mailbox_needs_reconnect`, `message_needs_reconnect`, `mailbox_not_connected`, `message_not_connected`, `message_account_restricted`	The inbox cannot send. `integration` names the setup page
`409`		Linking a sender who is already linked to another lead
`429`	`message_paced`, `message_rate_limited`, `mailbox_rate_limited`	Sending is paused; try again later
`502`	`mailbox_send_failed`, `message_send_failed`	The provider did not take the reply; try again

Errors use the standard body: { "statusCode", "message", "error" }, plus code where listed. Authenticated GET requests share a limit of 120 requests per endpoint per 10 seconds per person; a 429 carries Retry-After.