When a broker connects Gmail or Microsoft 365 in BrokerPlus, the API can read that mail too. You don't need a second connection to Gmail or Microsoft Graph. This page walks through one job end to end: a daily review that finds the email that needs an answer.
This API is in beta. Any endpoint can change in a breaking way without notice, so watch the changelog.
What a key can read
A key reads the mailboxes its broker can read in BrokerPlus, and no others. A teammate who hasn't shared their mailbox stays private.
BrokerPlus holds roughly the last six months of a mailbox and keeps it current from the moment it is connected. Sent and received mail are in the same list. Drafts aren't.
Read the mail
Every email is a communication. GET /v1/communications?channel=email lists them, newest first.
Code
read_at is null for mail nobody has opened. body is plain text and body_html is the sender's
HTML. BrokerPlus doesn't sanitize body_html, so sanitize it before you show it to anyone.
Attachments
Ask for an attachment by its id to get a download link:
Code
Code
The link works like a document download URL: it carries its own
authorization, so follow it right away and don't store or share it. BrokerPlus fetches the file from
the mail provider the first time anyone asks, so the first call on an old message is slower. If the
mailbox no longer has the message, you get 410 ATTACHMENT_UNAVAILABLE. A key with the
no_documents limit can't download attachments.
The filters a review needs
| Filter | What it does |
|---|---|
unread=true | Only mail nobody has opened. |
folder=inbox | One folder, by role or by the provider's own folder name. |
thread_id=... | Every message in one conversation. |
direction=inbound | Only mail that came in. |
updated_since=... | Mail that changed at or after this time: read, starred, filed on a deal, or moved between folders. |
A daily review asks for the unread inbox mail since the last run:
With updated_since the list runs oldest first, so you can page forward through a backlog; see
Sync. To read the conversation around a message, filter by its thread_id.
Get told instead of asking
Subscribe a webhook to email.received, and BrokerPlus calls you when mail arrives.
Code
The delivery carries the message's id; read it with GET /v1/communications/{id}. The event fires
for new mail only, not for junk and not for the history imported when a mailbox is first connected.
Act on a conversation
PATCH /v1/communications/{id} does what the inbox does: mark read or unread, mark done, star, set a
reminder, or file the mail on a deal. Each change applies to the whole conversation, as in the inbox,
and nothing goes to the client.
Code
Code
The response is shortened here. Marking mail read also marks it read in the broker's own mailbox. At
remind_at, the conversation comes back to the top of the inbox and the broker gets a notification;
with if_no_reply, the reminder is dropped if the client replies first.
Send deal_id to file the mail on a deal. Add "deal_scope": "message" to file only this message,
for example when one client writes about two deals in the same thread.
Tag a conversation
Inbox tags are the brokerage's own labels, such as Rate Hold or Docs Outstanding. They are a
separate list from contact tags and deal tags. GET /v1/communication-tags lists them, and
POST, PATCH and DELETE on /v1/communication-tags add, rename and archive them, the same as the
tag editor in the inbox.
POST /v1/communications/{id}/tags with a tag_id puts a tag on every message in the conversation.
DELETE /v1/communications/{id}/tags/{tagId} takes it off again. Each message lists its tags in
tags.
Code
On an Outlook mailbox, the tag is also written to Outlook as a category. BrokerPlus does not change
the labels of a Gmail mailbox, so a tag on Gmail mail gets 409 TAG_SYNC_UNSUPPORTED. A tag that
came from the mailbox itself cannot be renamed or archived while synced mail carries it.
File a conversation in a folder
Folders are the mailbox's own folders and labels, read from Gmail or Outlook.
GET /v1/communication-folders lists the folders of the broker's mailbox. Pass mailbox with an
address to list another mailbox the broker can read. Each message lists the folders it sits in, with
their ids, in folders.
POST /v1/communications/{id}/folders with a folder_id files every message in the conversation
into that folder, and DELETE /v1/communications/{id}/folders/{folderId} takes it out. The move
also happens in the broker's mail app a few seconds later. On Gmail a conversation can carry several
labels; on Outlook it moves to the one folder. Make, rename and delete folders in the mail app.
Snippets
Snippets are a broker's own saved replies. The broker types a snippet's shortcut in the composer to
insert it. GET /v1/snippets lists the snippets of the broker your key acts as, and POST, PATCH
and DELETE on /v1/snippets add, edit and delete them. You never see or change another broker's
snippets. Saving a snippet sends nothing.
Code
A shortcut is unique among the broker's snippets, so reusing one gets 409 DUPLICATE_SHORTCUT. If
you send body_html, unsafe HTML is removed from it, the same as for an email template. A snippet's
files are listed in attachments. GET /v1/snippets/{id}/attachments/{attachmentId} gives a link to
one of them that works for five minutes.
POST /v1/snippets/{id}/attachments adds a file, sent as multipart/form-data in a file field or as
JSON with file_name and content_base64. BrokerPlus reads the file's type from its content, not its
name. A PDF, JPEG, PNG, TIFF, WebP, Word or Excel file is stored as what it is. Content with no
recognisable type is accepted only as CSV, so a CSV sent as JSON needs a name ending in .csv.
Anything else gets 400 INVALID_TYPE. A snippet holds up to 10 files of at most 25 MB each.
DELETE /v1/snippets/{id}/attachments/{attachmentId} removes one.
Reply to a client
POST /v1/communications/{id}/reply answers a message in its own conversation, the same as Reply in
the inbox. The reply goes from the mailbox the conversation is on, with the conversation's subject,
so the client's mail program shows it in the same thread. A text is answered from the broker's
number, in the same text conversation.
Code
Code
The response is shortened here. The reply goes out at once, as the broker your key acts as, so a key
with the no_sending limit gets 403 KEY_LIMITED. See Reaching clients. An
email is sent in the background, so communication_id can be null for a short time.
mode picks who the reply goes to:
mode | Goes to |
|---|---|
reply (default) | The sender. On a message the broker sent, the people it was sent to. |
reply_all | The sender and everyone the message was sent to and copied, except the broker's own mailbox. |
forward | The addresses you send in to. The original message is quoted below body, and its files go with it. |
Send to to replace the addresses the mode picks, and cc or bcc to copy other people. To attach
a file, send it in attachments with file_name, content_type, and content_base64. A file can
be at most 10 MB, and the files of one email at most 25 MB together.
A forward carries the files of the email it forwards, before any you add. Send
"include_attachments": false to forward the text only. A picture shown inside the email body is
not sent as a file. If the email has a file that BrokerPlus can't send, such as a web page, the
forward gets 400, and you can forward it without its files.
When the conversation is on a mailbox the broker can read but cannot send from, such as a teammate's
shared mailbox, the reply gets 403 THREAD_VIEW_ONLY, as it does in the inbox.
Let the broker read it first
POST /v1/communications/{id}/drafts takes the same body and sends nothing. The reply waits in the
broker's drafts, in its conversation, and the broker sends, edits, or discards it in BrokerPlus.
Your system can also change it and send it:
PATCH /v1/drafts/{id}changes the subject, the text, the addresses, or the files.POST /v1/drafts/{id}/sendsends it now.POST /v1/drafts/{id}/discardthrows it away.
Send it later
Add send_at to a reply or to POST /v1/contacts/{id}/messages to send it at that time. The draft
is scheduled until then. POST /v1/drafts/{id}/schedule moves it to another time, or schedules a
draft that waits for review. POST /v1/drafts/{id}/unschedule stops it, and the draft waits for
review again.
Mail merges
A mail merge is one email that each person on a list gets on their own: nobody sees who else got
it. POST /v1/mail-merges sends one now, the same as Send merge in BrokerPlus. The response is 201
with the mail merge and a count of the addresses in each state. A key with the no_sending limit
gets 403 KEY_LIMITED.
Code
The merge goes from the mailbox of the broker your key acts as, to at most 500 addresses. Everybody
gets the same words, so a merge field such as {{first_name}} gets 400 TOKENS_NOT_SUPPORTED. A
person who unsubscribed or withdrew consent is skipped. Send schedule_at to send it later.
GET /v1/mail-merges lists the merges sent from the broker's mailbox, with how many addresses are
in each state. GET /v1/mail-merges/{id}/recipients shows what became of each address.
BrokerPlus does not keep the address on the merge: communication_id is the copy in Sent mail, and
contact_id is the contact with that address.
What you can't do yet
- Read the drafts a broker writes in BrokerPlus. You can read the drafts you file; see Drafts.
- Delete mail.
Tell us which of these you need, and we'll tell you where it sits in the queue.