Communications
Email, calls and messages on a deal or a contact.
List mail merges
The mail merges sent from the broker's mailbox, newest first, with how many addresses are in each state. A mail merge is one email that each person on a list gets on their own.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
List mail merges › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Send a mail merge
Sends one email to each address on the list now, or at schedule_at, from the mailbox of the broker your key acts as, the same as Send merge in BrokerPlus. Each person gets their own copy and sees no one else. A person who unsubscribed or withdrew consent is skipped. The response is 201 with the mail merge and a count for each state. Read each address with GET /v1/mail-merges/{id}/recipients. A key with the no_sending limit gets 403. Supports Idempotency-Key.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Send a mail merge › Request Body
The people to email, at most 500 different addresses. Each person gets their own copy and sees no one else. An address that is on the list twice gets one copy. A person who has no contact becomes a new lead.
bodyThe message, in plain text. Everybody gets the same words, so a merge field such as {{first_name}} is refused.
subjectThe subject of the email.
schedule_at^(?:(?:\d\d[2468][04…ISO 8601 date-time to send it at. Leave it out to send it now.
Send a mail merge › Responses
Success
successAlways true on a successful response.
The requested record.
List the recipients of a mail merge
What became of each address in a mail merge, in the order they were added. The address itself is not kept: communication_id is the copy in the broker's Sent mail, and contact_id is the contact with that address.
path Parameters
idResource id.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
statusOnly the recipients in this state.
List the recipients of a mail merge › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
List communications
Email, calls and messages, newest first, including mail that is not filed on a deal. updated_since pages on updated_at, which moves when a message is read, starred, filed on a deal or moved between folders. Subscribe to email.received to be told about new mail instead of polling for it.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
channelFilter by channel.
directioninbound or outbound.
deal_idOnly communications on this deal.
contact_idOnly communications this contact sent.
thread_idOnly messages in this conversation, oldest first when paired with updated_since.
folderOnly mail sitting in this folder, by role (inbox, sent) or by the provider's own name.
unreadtrue for mail nobody has opened yet, false for mail that has been read.
List communications › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Update a conversation
The actions of the inbox: mark read or unread, mark done, star, set a reminder, or file the mail on a deal. Each change applies to every message in the conversation of this message, as in the inbox. Nothing goes to the client. The response is this message after the change.
path Parameters
idResource id.
Update a conversation › Request Body
readtrue marks every message in the conversation read, false marks it unread. BrokerPlus also changes it in the broker's own mailbox.
donetrue marks the conversation done, which takes it out of the inbox. false puts it back.
starredStar or unstar the conversation.
remind_at^(?:(?:\d\d[2468][04…ISO 8601 date-time in the future. The conversation comes back to the top of the broker's inbox at that time, and the broker gets a notification. Send null to clear the reminder.
remind_conditionWith remind_at. if_no_reply cancels the reminder when the client replies first. Defaults to always.
deal_idFile the mail on this deal. Send null to take it off its deal. Nothing goes to the client.
deal_scopeWith deal_id. thread files every message in the conversation, and message files only this one. Defaults to thread.
Update a conversation › Responses
Success
successAlways true on a successful response.
The requested record.
Get a link to an attachment
A signed link to one attached file, valid for five minutes. BrokerPlus fetches the file from the mail provider the first time anybody asks for it, so the first call on an old message is slower than the rest. If the mailbox no longer holds the message, the response is 410 ATTACHMENT_UNAVAILABLE.
path Parameters
idResource id.
attachmentIdResource id.
Get a link to an attachment › Responses
Success
successAlways true on a successful response.
The requested record.
List snippets
The saved replies of the broker your key acts as, by shortcut. The broker types a snippet's shortcut in the composer to insert it. Another broker's snippets are never listed.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
List snippets › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create a snippet
Saves a reply for the broker your key acts as, as the snippet manager in the inbox does. Nothing is sent: the broker inserts it into mail they write.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create a snippet › Request Body
shortcut^[a-zA-Z0-9_-]+$ · requiredWhat the broker types to insert it: 1 to 40 letters, digits, _ or -. Unique among their snippets.
nameThe label in the snippet list, 80 characters or fewer.
bodyThe plain-text reply, 10,000 characters or fewer.
body_htmlThe reply with formatting, as HTML. Unsafe HTML is removed, as from an email template. Send null to keep only the plain text.
Create a snippet › Responses
Success
successAlways true on a successful response.
The requested record.
Update a snippet
Changes the shortcut, name or words of a snippet. Only the fields you send change.
path Parameters
idResource id.
Update a snippet › Request Body
shortcut^[a-zA-Z0-9_-]+$What the broker types to insert it: 1 to 40 letters, digits, _ or -. Unique among their snippets.
nameThe label in the snippet list, 80 characters or fewer.
bodyThe new plain-text reply.
body_htmlThe reply with formatting, as HTML. Unsafe HTML is removed, as from an email template. Send null to keep only the plain text.
Update a snippet › Responses
Success
successAlways true on a successful response.
The requested record.
Attach a file to a snippet
Adds a file that goes out with the mail the snippet is inserted into. Send it as multipart/form-data in a file field, or as JSON with content_base64. BrokerPlus reads the type from the content, not the name: a PDF, image, Word or Excel file is stored as what it is, and content with no recognisable type is taken only as CSV. A snippet holds up to 10 files. Nothing is sent.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Attach a file to a snippet › Request Body
fileThe file: PDF, JPEG, PNG, TIFF, WebP, Word (.docx), Excel (.xlsx), or CSV, at most 25 MB. Its file name is the name the broker sees.
Attach a file to a snippet › Responses
Success
successAlways true on a successful response.
The requested record.
Get a link to a snippet's file
A signed link to one file of a snippet, valid for five minutes.
path Parameters
idResource id.
attachmentIdResource id.
Get a link to a snippet's file › Responses
Success
successAlways true on a successful response.
The requested record.
Remove a file from a snippet
Takes the file off the snippet and deletes it. Mail already sent with it keeps its copy.
path Parameters
idResource id.
attachmentIdResource id.
Remove a file from a snippet › Responses
Success
successAlways true on a successful response.
The requested record.
File a conversation in a folder
Files every message in the conversation of this message into a folder of the mailbox that holds it, as filing does in the inbox. The move also happens in the broker's own mail app, a few seconds later. On Gmail a conversation can sit in several labels; on Outlook it moves to the one folder. Nothing goes to the client. The response is this message after the change.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
File a conversation in a folder › Request Body
folder_idA folder id from GET /v1/communication-folders, in the mailbox that holds the message.
File a conversation in a folder › Responses
Success
successAlways true on a successful response.
The requested record.
Take a conversation out of a folder
Takes every message in the conversation of this message out of a folder of its mailbox. On Gmail this removes the label. Taking a conversation out of a folder it is not in changes nothing. The response is this message after the change.
path Parameters
idResource id.
folderIdResource id.
Take a conversation out of a folder › Responses
Success
successAlways true on a successful response.
The requested record.
List mail folders
The folders and labels of one connected mailbox, by name. Without mailbox this is the broker's own mailbox, or the team's shared one when the broker has none, the same tree the inbox shows. With no mailbox connected, the list is empty. Folders are made and renamed in the mail app; BrokerPlus reads them from there.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
mailboxThe address of a connected mailbox that the broker can read, as mailbox on a communication shows it.
List mail folders › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Put a tag on a conversation
Puts an inbox tag on every message in the conversation of this message, as in the inbox. Putting on a tag the conversation already has changes nothing. On an Outlook mailbox the tag is also written to Outlook as a category. Nothing goes to the client. The response is this message after the change.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Put a tag on a conversation › Request Body
tag_idA tag id from GET /v1/communication-tags.
Put a tag on a conversation › Responses
Success
successAlways true on a successful response.
The requested record.
Take a tag off a conversation
Takes an inbox tag off every message in the conversation of this message. Taking off a tag that is not there changes nothing. The response is this message after the change.
path Parameters
idResource id.
tagIdResource id.
Take a tag off a conversation › Responses
Success
successAlways true on a successful response.
The requested record.
List inbox tags
The brokerage's inbox tags, in display order. A broker puts them on conversations in the inbox. Contact tags and deal tags are separate lists.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
List inbox tags › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create an inbox tag
Adds a tag to the brokerage's inbox tags. The new tag goes to the end of the order. A name that an archived tag had restores that tag.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create an inbox tag › Request Body
nameThe label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind.
colorThe swatch: navy, amber, slate, red, or a #rrggbb hex. Defaults to navy. Cosmetic.
Create an inbox tag › Responses
Success
successAlways true on a successful response.
The requested record.
Archive an inbox tag
Removes the tag from the list and from every conversation that has it, as Delete does in the inbox. To restore the name, create a tag with the same name. The conversations do not get the tag back.
path Parameters
idResource id.
Archive an inbox tag › Responses
Success
successAlways true on a successful response.
The requested record.
Update an inbox tag
Changes the name or colour of an inbox tag. Every conversation that has the tag keeps it.
path Parameters
idResource id.
Update an inbox tag › Request Body
nameThe label brokers see, 40 characters or fewer. It must be unique among the live tags of its kind.
colorThe swatch: navy, amber, slate, red, or a #rrggbb hex. Defaults to navy. Cosmetic.
Update an inbox tag › Responses
Success
successAlways true on a successful response.
The requested record.
List recorded meetings
The video meetings BrokerPlus took notes in, as the Meetings tab lists them, with BrokerPlus's summary. Newest first, or oldest first with updated_since. Read the transcript with GET /v1/meetings/{id}. The recording itself is not on the API.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
deal_idOnly meetings filed on this deal.
contact_idOnly meetings with this client.
List recorded meetings › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Send the notetaker into a call
Sends the BrokerPlus notetaker into a Zoom, Google Meet or Microsoft Teams call, now or at join_at, as the broker your key acts as. Everybody in the call sees it join. The response is 201 with the new meeting. Its transcript and summary arrive on it after the call ends: read them with GET /v1/meetings/{id}. A key with the no_sending limit gets 403. Supports Idempotency-Key.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Send the notetaker into a call › Request Body
meeting_urlThe Zoom, Google Meet or Microsoft Teams link of the call the notetaker joins.
deal_idThe deal to file the meeting on. Leave it out to file it on none.
bot_nameThe name everybody in the call sees. Leave it out for the brokerage's default notetaker name.
join_at^(?:(?:\d\d[2468][04…When the notetaker joins, in UTC, for example 2026-10-14T15:00:00Z. Leave it out to join now.
Send the notetaker into a call › Responses
Success
successAlways true on a successful response.
The requested record.
Retrieve a recorded meeting
One meeting with its transcript line by line, who was in it and how long each person spoke, BrokerPlus's follow-ups, and the video platform's own summary when it writes one.
path Parameters
idResource id.
Retrieve a recorded meeting › Responses
Success
successAlways true on a successful response.
The requested record.
Take the notetaker out of a call
Takes the notetaker out of the call before it ends, and answers the meeting. A meeting already stopped is answered as it stands. A Roam meeting has no notetaker to take out: it is stopped from inside Roam.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Take the notetaker out of a call › Responses
Success
successAlways true on a successful response.
The requested record.
Pull a meeting's transcript again
Asks the video platform for the meeting's recording details, transcript and summary again, as the Sync button does, for a meeting that ended without them. The work runs in the background: the response is the meeting as it stands now, and the new transcript lands on it within a few minutes.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Pull a meeting's transcript again › Responses
Success
successAlways true on a successful response.
The requested record.
Reply to a message
Answers an email or text in its own conversation, as Reply, Reply All or Forward does in the inbox: from the mailbox or number the conversation is on, with the conversation's subject, so the client's mail program shows it in the same thread. Set send_at to send it later. The reply is the broker's own: it is in their drafts folder as sent (or scheduled), and in Sent. The response is 201 with the draft. A key with the no_sending limit gets 403. Supports Idempotency-Key.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Reply to a message › Request Body
modereply answers the sender. reply_all also addresses everyone the message was sent to and copied, except the mailbox the reply leaves from. forward sends the message on to the addresses in to, quoted below body. A text takes reply only. Answering a message the broker sent goes to the people it was sent to.
bodyThe text the client reads, above any forwarded message. Plain text. A text over 1600 characters is refused.
body_htmlA formatted version of an email body. Leave it out to send body as written. Not accepted for a text, or for a forward.
subjectLeave it out to keep the conversation's subject, starting Re: or Fwd:. A different subject can make the client's mail program show the reply as a new conversation. Not accepted for a text.
Who the email goes to. Required for forward. For reply and reply_all, leave it out to use the addresses the mode picks, or send it to replace them. Not accepted for a text.
Addresses to copy on the email. Not accepted for a text.
Addresses to blind-copy on the email. Not accepted for a text.
Files the email carries, at most 10. Not accepted for a text.
include_attachmentsFor forward only. The forward carries the files of the email it forwards, before any in attachments. Set it to false to forward the text only. A picture shown inside the email body is not sent as a file.
send_atWhen the message goes out, as an ISO 8601 timestamp in the future. Leave it out to send now. Until then the draft is scheduled: move it with POST /drafts/{id}/schedule, or stop it with POST /drafts/{id}/unschedule.
Reply to a message › Responses
Success
successAlways true on a successful response.
The requested record.
Draft a reply to a message
Writes a reply, reply-all or forward into the drafts of the broker your key acts as, in the message's conversation, and sends it to nobody. The broker finds it under the conversation in their inbox and in their drafts folder, and sends, edits or discards it there. You can also change it with PATCH /drafts/{id} and send it with POST /drafts/{id}/send.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Draft a reply to a message › Request Body
modereply answers the sender. reply_all also addresses everyone the message was sent to and copied, except the mailbox the reply leaves from. forward sends the message on to the addresses in to, quoted below body. A text takes reply only. Answering a message the broker sent goes to the people it was sent to.
bodyThe text the client reads, above any forwarded message. Plain text. A text over 1600 characters is refused.
body_htmlA formatted version of an email body. Leave it out to send body as written. Not accepted for a text, or for a forward.
subjectLeave it out to keep the conversation's subject, starting Re: or Fwd:. A different subject can make the client's mail program show the reply as a new conversation. Not accepted for a text.
Who the email goes to. Required for forward. For reply and reply_all, leave it out to use the addresses the mode picks, or send it to replace them. Not accepted for a text.
Addresses to copy on the email. Not accepted for a text.
Addresses to blind-copy on the email. Not accepted for a text.
Files the email carries, at most 10. Not accepted for a text.
include_attachmentsFor forward only. The forward carries the files of the email it forwards, before any in attachments. Set it to false to forward the text only. A picture shown inside the email body is not sent as a file.
Draft a reply to a message › Responses
Success
successAlways true on a successful response.
The requested record.