Connected inboxes

A connected inbox (in the API, a connected account) is a mailbox, WhatsApp, Instagram, LinkedIn or Telegram account a member connected to Fondaro. Use these endpoints to manage inboxes and to email or message a lead from them; every email and message goes out from the person's own account.

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. Each member connects at most one inbox of each kind. Connecting is a browser round trip: you get a link, the person signs in with the provider, and Fondaro never receives a password.

The connected account object

needs_reconnect means the provider stopped accepting the connection (a changed password, or access removed). Reconnecting restores it with the same id.

List your inboxes

GET /connected-accounts

Returns your live inboxes and the colleagues' inboxes an admin gave you. available is false when connecting is not available; the lists are then empty.

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

{  "available": true,  "accounts": [    {      "id": "3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84",      "kind": "mailbox",      "provider": "google",      "address": "agent@example.com",      "status": "ok",      "statusReason": null,      "statusChangedAt": "2026-09-25T09:14:03.000Z",      "capabilities": ["email", "calendar"],      "connectedAt": "2026-09-25T09:14:03.000Z",      "disconnectedAt": null,      "ownerUserId": "user_2a",      "assignedUserIds": [],      "calendars": [        { "id": "agent@example.com", "name": "agent@example.com", "primary": true, "readOnly": false, "selected": true }      ]    }  ],  "assigned": []}

List the organization's inboxes

GET /connected-accounts/organization

Admins only. Returns every member's live inboxes as an array. Each item adds owner (name, email, imageUrl) and included (true when it is one of the plan's included inboxes, the oldest ones; false when it is one of the extra inboxes bought).

curl "https://api.fondaro.com/connected-accounts/organization" \  -H "Authorization: Bearer $SESSION_TOKEN"

[  {    "id": "3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84",    "kind": "mailbox",    "provider": "microsoft",    "address": "agent@example.com",    "status": "needs_reconnect",    "ownerUserId": "user_2b",    "assignedUserIds": [],    "owner": { "name": "Agent Name", "email": "agent@example.com", "imageUrl": null },    "included": true  }]

Check the price of the next inbox

GET /connected-accounts/price

Returns whether the next inbox fits in your organization's inboxes, how many are free, the price of one extra inbox, and whether you may add one to the plan yourself.

curl "https://api.fondaro.com/connected-accounts/price" \  -H "Authorization: Bearer $SESSION_TOKEN"

{  "included": false,  "room": 0,  "amountCents": 1000,  "currency": "EUR",  "canAddPaid": false,  "requests": [    { "id": "6f0c1d2e-8a3b-4c5d-9e7f-0a1b2c3d4e5f", "kind": "whatsapp", "provider": "whatsapp", "status": "pending", "askedAt": "2026-09-30T09:12:00.000Z", "answeredAt": null }  ]}

GET /billing/plan-usage returns the plan's people and inbox totals:

{  "inboxes": {    "included": 5,    "bonus": 0,    "bought": 2,    "capacity": 7,    "inUse": 6,    "room": 1,    "pricePerInbox": 1000,    "monthlyBought": 2000  }}

included is one inbox per member plus any bonus; capacity is included + bought; room is capacity - inUse, never below 0. monthlyBought is null for a member.

Change your inboxes

Admins only. Each extra inbox is a monthly charge on your plan, like a person. inboxes is always the total after the change (included plus bought).

GET /billing/inboxes/preview?inboxes=7 previews the change without making it:

curl "https://api.fondaro.com/billing/inboxes/preview?inboxes=7" \  -H "Authorization: Bearer $SESSION_TOKEN"

{  "currency": "EUR",  "dueToday": 640,  "lines": [{ "description": "Remaining time on 1 × Extra inboxes", "amount": 640 }],  "nextAmount": 2000,  "nextDate": "2026-11-01T00:00:00.000Z",  "inboxes": { "from": 6, "to": 7, "included": 5, "bonus": 0, "boughtFrom": 1, "boughtTo": 2, "inUse": 6, "pricePerInbox": 1000 }}

PATCH /billing/inboxes makes it. Send a fresh requestId per change and the same one when you retry it, so a retry never adds twice.

curl -X PATCH "https://api.fondaro.com/billing/inboxes" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"inboxes": 7, "requestId": "3a1f2b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b"}'

{ "inboxes": 7, "bought": 2, "inUse": 6 }

Adding inboxes is charged now for the rest of the billing period, and lands only once that payment succeeds (402 PAYMENT_ACTION_REQUIRED otherwise). Removing inboxes credits the unused days on the next invoice. During a trial nothing is charged until it ends.

Connect an inbox

POST /connected-accounts/connect

Starts a connection and returns a url to open in the person's browser. They return to the matching Integrations page with ?connected=<provider> on success or ?connect_error=<reason> on failure.

curl -X POST "https://api.fondaro.com/connected-accounts/connect" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"provider": "google"}'

{ "url": "https://..." }

The inbox appears in GET /connected-accounts once the provider confirms it; poll until status is ok.

When every inbox is in use, connecting is refused with the facts in the body (capacity, inUse, pricePerInbox): an admin gets 409 inboxes_full (add an inbox first with PATCH /billing/inboxes), a member 403 admin_approval_required (ask for one). Connecting itself never charges anything.

Choose whether past messages come in

PATCH /connected-accounts/:id

Each inbox has a history choice. from_now brings in only new mail and messages: no import of the past when it connects, and no pull of a chat's past when a lead first writes. last_90_days imports the last 90 days of mail with people who are already your leads when it connects, and pulls the last 90 days of a chat when a lead first writes. Find past emails and Find past messages are your own request on one lead and work in either case.

Only the person who connected the inbox can change it (for the shared inbox, the admin who connected it). Switching a healthy mailbox to last_90_days starts the mail import once, in the background. Switching to from_now stops later pulls and deletes nothing. Inboxes connected before 29 October 2026 are from_now.

curl -X PATCH "https://api.fondaro.com/connected-accounts/3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"historyMode": "last_90_days"}'

Returns the inbox. An admin can turn past messages off for the whole agency with PATCH /organization/inbox-settings and {"inboxHistoryAllowed": false}; every inbox then behaves as from_now, and asking for last_90_days returns 409 history_off.

Share your conversations on a lead

GET /connected-accounts/sharing, PATCH /connected-accounts/sharing

One switch per person, off until you turn it on. With it on, a colleague assigned to the same lead as you sees your emails and messages with that lead on the lead's page in Fondaro, read-only. They can't see your inbox, reply from it, or open its files, and your conversations never appear in their Inbox. It covers every inbox you connected except the shared inbox. Only your own switch is read or changed here; nobody else's, an admin's included.

curl -X PATCH "https://api.fondaro.com/connected-accounts/sharing" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"shareWithLeadColleagues": true}'

Both return { "shareWithLeadColleagues": true, "agencyAllows": true }. An admin can turn sharing off for the whole agency with PATCH /organization/inbox-settings and {"inboxSharingAllowed": false}: nothing is shared then, whatever each person chose, and turning it back on restores each person's own choice. While it is off, turning your switch on returns 409 sharing_off; turning it off always works.

Ask for an inbox

POST /connected-accounts/requests

When every inbox is in use, a member asks the admins instead (body as for connect). While one is free, asking returns 409 not_needed: connect instead. Admins get a notification and see the request on Settings › Me › Inboxes. Asking again for the same kind returns the open request.

curl -X POST "https://api.fondaro.com/connected-accounts/requests" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"provider": "whatsapp"}'

{ "id": "6f0c1d2e-8a3b-4c5d-9e7f-0a1b2c3d4e5f", "kind": "whatsapp", "provider": "whatsapp", "status": "pending", "askedAt": "2026-09-30T09:12:00.000Z", "answeredAt": null }

Admins list open requests with GET /connected-accounts/requests (each adds userId, requester and the monthly amountCents and currency), and answer with POST /connected-accounts/requests/:id/allow or POST /connected-accounts/requests/:id/decline. Allowing tells the member they can connect. They connect while an inbox is free, so when every inbox is in use, add one with PATCH /billing/inboxes before allowing. Answering a request that is no longer open returns 409 request_closed.

Give an inbox to other people

PUT /connected-accounts/:id/assignees

Admins only. Sets everyone besides the owner who uses this inbox (such as the agency's info@). They see its new conversations and can send from it. Replaces the whole list.

curl -X PUT "https://api.fondaro.com/connected-accounts/8d2a61f0-5c3e-4b7a-a1d9-6e4f0b2c7a15/assignees" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"userIds": ["user_2b", "user_2c"]}'

{ "id": "8d2a61f0-5c3e-4b7a-a1d9-6e4f0b2c7a15", "kind": "shared_mailbox", "address": "info@example.com", "assignedUserIds": ["user_2b", "user_2c"] }

Reconnect an inbox

POST /connected-accounts/:id/reconnect

Returns a url, as for connect. Only the member who connected the inbox can reconnect it. It keeps its id and uses no extra inbox.

curl -X POST "https://api.fondaro.com/connected-accounts/3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84/reconnect" \  -H "Authorization: Bearer $SESSION_TOKEN"

{ "url": "https://..." }

Disconnect an inbox

DELETE /connected-accounts/:id

Disconnects at once and answers 204 with no body. The owner or any admin can disconnect. Conversations already on leads stay. There is no refund for the current month.

curl -X DELETE "https://api.fondaro.com/connected-accounts/3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84" \  -H "Authorization: Bearer $SESSION_TOKEN"

Choose which calendars show

A Google or Microsoft inbox with the calendar capability lists its calendars in calendars. A calendar someone else owns and shared into the inbox is listed only when the inbox's owner is an organization admin; for a member it is left out and its events leave their calendar.

PUT /connected-accounts/:id/calendars/:calendarId with { "selected": true | false } shows or hides one calendar. POST /connected-accounts/:id/calendars/refresh (no body) lists the calendars again, for one made after connecting. Both act on your own inbox only and answer { "calendars": [...] }.

curl -X PUT "https://api.fondaro.com/connected-accounts/3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84/calendars/viewings%40group.calendar.google.com" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"selected": false}'

{  "calendars": [    { "id": "agent@example.com", "name": "agent@example.com", "primary": true, "readOnly": false, "selected": true },    { "id": "viewings@group.calendar.google.com", "name": "Viewings", "primary": false, "readOnly": false, "selected": false }  ]}

Email a lead

See which address you send from

GET /crm/email-sender

Returns how an email you send now would leave, so a composer can show the From address or a Connect step.

curl "https://api.fondaro.com/crm/email-sender" \  -H "Authorization: Bearer $SESSION_TOKEN"

{  "via": "mailbox",  "address": "sofia@example.com",  "status": "ok",  "accountId": "3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84",  "options": [    { "accountId": "3c9e2f41-7b1d-4c8a-9e53-0a6d2b7f1e84", "address": "sofia@example.com", "via": "mailbox" },    { "accountId": "8d2a61f0-5c3e-4b7a-a1d9-6e4f0b2c7a15", "address": "info@example.com", "via": "shared_mailbox" }  ]}

via is mailbox or none (nothing to send from). An inbox that needs reconnecting still answers mailbox with its status. options lists every inbox you may pick as From whose status is ok: your own, then those an admin gave you.

Send an email

POST /crm/leads/:id/emails

Sends from your connected mailbox. It lands in your Sent folder, and the lead's reply comes back to your inbox and onto the lead.

curl -X POST "https://api.fondaro.com/crm/leads/4821/emails" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"subject": "Re: The villa in Nueva Andalucía", "bodyText": "Saturday at 11 works for me.", "replyToEmailId": "b7e1c5d2-4a3f-4e8b-9c61-2d0f7a9e5b13"}'

The response is the email as it now sits on the lead's timeline, with toAddresses, ccAddresses and bccAddresses.

Find past emails

POST /crm/leads/:id/find-past-emails

Searches your connected inboxes for the lead's email address over the last 12 months and adds what it finds to the lead within a minute or two. Use it for a lead created after you connected (connecting brings in the last 90 days once). Safe to repeat. Answers 202.

curl -X POST "https://api.fondaro.com/crm/leads/4821/find-past-emails" \  -H "Authorization: Bearer $SESSION_TOKEN"

{ "mailboxes": 1, "found": 6, "enqueued": 4 }

Message a lead

List the lead's channels

GET /crm/leads/:id/channels

Lists the channels you can message this lead on: you have a live WhatsApp, Instagram, LinkedIn or Telegram connection and the lead is reachable there (on WhatsApp by their number, elsewhere because they wrote to you or a member linked their profile). An empty list means no message channel.

curl "https://api.fondaro.com/crm/leads/4821/channels" \  -H "Authorization: Bearer $SESSION_TOKEN"

{  "channels": [    {      "channel": "whatsapp",      "canSend": true,      "block": null,      "integration": "whatsapp",      "accountAddress": "+34600000001",      "counterpart": "+34600000002",      "newChat": true,      "manyNewChats": false    }  ]}

block says why canSend is false: needs_reconnect or restricted (the provider restricted the account). newChat is true when the next message opens a chat with someone new. manyNewChats is true when it does and the account has already started many new chats in the last 24 hours: advice to spread them out, never a block.

Send a message

POST /crm/leads/:id/messages

Sends from your own connection of that channel. A person sends every message: there is no scheduled, bulk or automated sending.

curl -X POST "https://api.fondaro.com/crm/leads/4821/messages" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"channel": "whatsapp", "body": "Saturday at 11 works for me."}'

{  "id": "6a1f0c3e-2b7d-4e59-8c14-9d3a5e7b2f60",  "leadId": 4821,  "channel": "whatsapp",  "kind": "text",  "direction": "outbound",  "status": "sent",  "body": "Saturday at 11 works for me.",  "attachments": [],  "messageAt": "2026-09-25T10:04:00.000Z"}

To protect your account, messages from one account go at least 15 seconds apart (Instagram 10 seconds, and at most 10 an hour); a send inside that gap waits up to 30 seconds. A first message to someone new is never held back.

GET /crm/leads/:id/messages/:messageId/attachments/:index returns a short-lived download link (url, filename, contentType) for a stored file on a message.

Link a lead's channel

Link a WhatsApp number, Instagram, LinkedIn or Telegram identity, or an extra email address, to a lead so messages there land on it.

curl -X POST "https://api.fondaro.com/crm/leads/4821/channel-identities" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"channel": "whatsapp", "value": "+34600000002"}'

{  "identity": { "id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "channel": "whatsapp", "display": "+34600000002", "linkedBy": "user_2a", "createdAt": "2026-09-25T10:00:00.000Z" },  "attachedMessages": 3,  "attachedEmails": 0}

Look up a lead's profile

POST /crm/leads/:id/lookup-profile

Reads the lead's linked LinkedIn or Instagram profile once, through your own connection. It changes nothing on the lead. LinkedIn allows about 80 look ups a day per account.

curl -X POST "https://api.fondaro.com/crm/leads/4821/lookup-profile" \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"channel": "linkedin"}'

{  "channel": "linkedin",  "identity": "sample-buyer",  "name": "Sample Buyer",  "headline": "Relocating to Marbella",  "company": "Example Ltd",  "location": "London",  "category": null,  "emails": [],  "phones": [],  "profileUrl": "https://www.linkedin.com/in/sample-buyer"}

Errors

Errors use the standard body { "statusCode", "message", "error" }, plus code and any fields listed above.