API reference Email
Email Service API Endpoints (Connected Mailboxes)
The production API base URL is https://api.tradesmentechnologies.com/.
Authentication
All endpoints require a Bearer token in the Authorization header:
Authorization: Bearer <your_token>
Mutating requests may carry an Idempotency-Key header so a retry never acts twice — see Idempotent Retries in the Accounts API documentation.
Base Path
/prod/email
Authorization
- Connect, test, disconnect (
POST /email/accounts/imap/test,POST /email/accounts/imap,DELETE /email/accounts/{accountId},GET /email/providers/detect):ADMINemployees only. - Read and sync (
GET /email/accounts,POST /email/sync,POST /email/accounts/{accountId}/sync,GET /email/messages,GET /email/messages/{messageId},PATCH /email/messages/{messageId}):ADMINandLEAD_TECHNICIANemployees. Technicians have no access to email; a technician receives403withcode: EMAIL_ACCESS_DENIED.
Overview
A company connects the mailboxes it uses with its customers so that its email conversations with those customers appear in the app. The integration is read-only: the platform never sends mail from a connected mailbox and never changes anything in it (no flags, no moves, no deletes). Replies are written in the company's own mail client and appear through the Sent folder.
What is synced and stored:
- The Inbox and Sent folders of each connected mailbox, looking back one year when the mailbox is first connected and incrementally afterwards.
- Only messages in which at least one sender or recipient is a customer saved in the company (matched on the customer's
emailandadditionalEmails). Every other message is skipped and not retained. Matching uses the customer list as it is when the message is synced. An address added to a customer later matches mail that arrives from then on; mail synced before the change is not revisited automatically —POST /email/accounts/{accountId}/rescanwalks the last year of the mailbox again against the current list. - For a stored message: the headers, the plain-text body and the HTML body. Attachments are never downloaded or stored: the message lists each attachment's name, type and approximate size so the app can show that it exists, and the file itself stays in the mailbox. A text or HTML body larger than 2 MB is left out and the message is flagged
truncated: true. - One email is stored once, whoever it involves. A message in which several saved customers take part (a shared address, a customer copied on another's email) is a single stored message that appears in each of those customers' conversations;
customerIdslists them all.
Freshness: mail is fetched when the app asks for it, not on a schedule. The app calls POST /email/sync when it opens the conversations (and on pull-to-refresh); that starts a sync of every connected mailbox not synced in the last minute and returns at once. The app then shows the current list, watches syncing on GET /email/accounts, and reloads the list when it turns false — typically within a few seconds for a handful of new messages. A mailbox nobody opens is never read. One mailbox alone can be synced with POST /email/accounts/{accountId}/sync.
Several mailboxes may be connected per company (up to 10); a customer's conversation merges every mailbox.
Disconnecting a mailbox deletes its stored credential at once and then every message synced from it.
Connecting a mailbox
GET /email/providers/detect?email=…tells the app how the address can be connected: the provider, whether a Google / Microsoft sign-in is available for it, the IMAP settings to prefill, and the instructions to show (for example how to create an app password).- For a provider connected with a password or app password, the app may call
POST /email/accounts/imap/testto check the settings without storing anything, thenPOST /email/accounts/imapto connect. The connect call tests the login again, stores the credential encrypted, and starts the first sync in the background (status: SYNCINGuntil the one-year backfill is done, thenACTIVE). - Google and Microsoft sign-in (
authTypeOAUTH_GOOGLE/OAUTH_MICROSOFT) are reported by detection withoauthAvailable: falseuntil those flows are released. A Google mailbox can meanwhile be connected with a Google app password through the IMAP endpoints (passwordSupported: true); a Microsoft mailbox cannot be connected yet (unsupportedReason: MICROSOFT_OAUTH_PENDING).
Session bootstrap
The login / session payload carries an emailIntegration summary of the company's connected mailboxes (never the messages):
{
"emailIntegration": {
"accounts": [
{ "accountId": "6f1c…", "email": "office@acmeplumbing.com", "provider": "GODADDY", "status": "ACTIVE" }
]
}
}
An account whose purge is still running after a disconnect is not listed.
Enums
Provider (provider): GOOGLE, MICROSOFT, YAHOO, AOL, ICLOUD, ZOHO, GODADDY, FASTMAIL, OTHER.
Auth type (authType): OAUTH_GOOGLE, OAUTH_MICROSOFT, PASSWORD.
Account status (status):
| Status | Meaning |
|---|---|
SYNCING |
Connected; the one-year backfill (first connect, or a rescan) is still running. Messages already appear as they are stored. |
ACTIVE |
Connected; synced whenever the app asks. |
NEEDS_REAUTH |
The provider refused the stored credential (changed password, revoked app password). Nothing is synced until the mailbox is reconnected; the admin who connected it is emailed once. Because a sync only runs when someone opens the conversations, this is noticed at that moment — show it on the conversations screen. |
ERROR |
Three or more consecutive failures that were not a login problem (unreachable server, TLS error). The next sync request still tries again. |
DISCONNECTED |
Disconnected by an admin; its messages are being deleted. Not listed by GET /email/accounts. |
Message direction (direction): INBOUND (sent to the company) or OUTBOUND (sent by one of the company's connected mailboxes).
Connection error codes (code on a failed test / connect): AUTH_FAILED (wrong password or app password, or the provider requires an app password), TLS_FAILED (the server's certificate could not be verified or it would not encrypt), HOST_UNREACHABLE (name or port wrong, firewall, timeout), IMAP_DISABLED (IMAP is turned off for the mailbox or its organization), UNKNOWN.
Detection source (source): DOMAIN (a well-known address domain), MX (the domain's mail records named the provider), AUTOCONFIG (settings found in the public mail autoconfiguration database), GUESS (nothing was found; the settings are a guess the user must confirm).
Entities
Email account
{
"accountId": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"email": "office@acmeplumbing.com",
"displayName": "Office",
"provider": "GODADDY",
"authType": "PASSWORD",
"status": "ACTIVE",
"imap": { "host": "imap.secureserver.net", "port": 993, "secure": true },
"lastSyncAt": "2026-11-02T15:05:12.000Z",
"lastError": null,
"lastErrorAt": null,
"backfillCompletedAt": "2026-11-01T09:12:00.000Z",
"syncing": false,
"pushActive": false,
"connectedBy": "employee-id",
"createdAt": "2026-11-01T09:00:00.000Z",
"updatedAt": "2026-11-02T15:05:12.000Z"
}
Credentials are never returned. imap is null for accounts that will use a Google / Microsoft sign-in. lastError is one of the connection error codes above when the last sync failed. syncing is true while a sync of the mailbox is running — poll GET /email/accounts after POST /email/sync and reload the messages when it clears. pushActive is false for every password account and reserved for the provider-notification phases.
Email message
List views (from GET /email/messages) carry every field below except textBody, htmlUrl and primaryCustomerId; the detail view (GET /email/messages/{messageId}) carries them all.
{
"messageId": "3f9a0c1d2e4b5a6f7c8d9e0f1a2b3c4d",
"accountId": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"accountEmail": "office@acmeplumbing.com",
"folder": "INBOX",
"direction": "INBOUND",
"from": { "name": "Dana Customer", "address": "dana@example.org" },
"to": [ { "name": "Acme Plumbing", "address": "office@acmeplumbing.com" } ],
"cc": [],
"subject": "Re: Invoice 123",
"snippet": "Hi there, see attached.",
"textBody": "Hi there, see attached.",
"hasHtml": true,
"htmlUrl": "https://…signed URL, valid one hour…",
"attachmentCount": 1,
"attachments": [
{ "attachmentId": "a1", "fileName": "note.pdf", "contentType": "application/pdf", "size": 48213, "inline": false },
{ "attachmentId": "a2", "fileName": "logo.png", "contentType": "image/png", "size": 2048, "inline": true }
],
"customerIds": ["customer-id", "other-customer-id"],
"primaryCustomerId": "customer-id",
"threadKey": "9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
"messageIdHeaderHash": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
"inReplyTo": "<root@acmeplumbing.com>",
"receivedAt": "2026-11-02T15:00:00.000Z",
"syncedAt": "2026-11-02T15:05:12.000Z",
"truncated": false,
"jobId": null,
"readAt": null
}
messageIdis stable: syncing the same message again never creates a second row.customerIdslists every saved customer among the participants (a shared address can match several); the message is stored once and appears in each of their conversations.primaryCustomerIdis the sender for inbound mail and the first matched recipient for outbound mail.threadKeygroups a conversation (the first id of the message'sReferenceschain, else itsIn-Reply-To, else its own id); group by it to render threads.messageIdHeaderHashis the same for one email seen through two connected mailboxes (one was copied on the other); de-duplicate on it when merging mailboxes.attachmentsis metadata only: the file is not stored and there is nothing to download.sizeis approximate (derived from the message structure).inline: truemarks a part embedded in the HTML body (an image, a signature logo);attachmentCountcounts the others. Images referenced by the HTML throughcid:links are therefore not available and render as missing.htmlUrlis a presigned link valid for one hour. Render HTML in an isolated web view with remote images blocked by default.truncated: truemeans a text or HTML body part was over 2 MB and was left out; the headers and the other part are intact.jobIdis set byPATCH /email/messages/{messageId};readAtis the in-app read marker (the mailbox's own read flags are never touched).
Endpoints
Detect Provider
- Method: GET
- Path:
/prod/email/providers/detect?email=office@acmeplumbing.com - Auth:
ADMIN - Response (200):
{
"provider": "GODADDY",
"authType": "PASSWORD",
"oauthAvailable": false,
"passwordSupported": true,
"imap": { "host": "imap.secureserver.net", "port": 993, "secure": true },
"imapGuessed": false,
"instructions": {
"title": "GoDaddy Professional Email",
"steps": ["Enter the email address and the password you use to sign in to GoDaddy webmail."]
},
"unsupportedReason": null,
"source": "MX"
}
instructions.url (optional) links to the provider's app-password page. imapGuessed: true means the settings were not found anywhere and are a guess (mail.<domain>, port 993) the user must confirm or correct. unsupportedReason is MICROSOFT_OAUTH_PENDING for a Microsoft mailbox and PROTON_BRIDGE_REQUIRED for Proton Mail; such an address cannot be connected through the IMAP endpoints (passwordSupported: false).
- Errors:
400missing or malformedemail;403not an admin.
Test IMAP Settings
- Method: POST
- Path:
/prod/email/accounts/imap/test - Auth:
ADMIN - Body:
{
"email": "office@acmeplumbing.com",
"password": "the mailbox password or app password",
"imap": { "host": "imap.secureserver.net", "port": 993, "secure": true }
}
imap.secure: true is TLS on connect (port 993); false is STARTTLS on a clear port (143), and the connection is refused if the server will not upgrade to TLS. Certificates are always verified.
- Response (200):
{ "ok": true, "sentFolder": "Sent" }when the login works (sentFolderis the folder that will be synced as Sent, ornullwhen the server has none), or{ "ok": false, "code": "AUTH_FAILED" }with one of the connection error codes. Nothing is stored either way. - Errors:
400invalid body (email syntax, empty password, bad host or port);403not an admin.
Connect IMAP Mailbox
- Method: POST
- Path:
/prod/email/accounts/imap - Auth:
ADMIN - Body: the same as Test IMAP Settings, plus an optional
displayName(≤ 120 characters). - Response (201):
{
"message": "Mailbox connected",
"account": { "accountId": "6f1c…", "email": "office@acmeplumbing.com", "provider": "GODADDY", "authType": "PASSWORD", "status": "SYNCING", "imap": { "host": "imap.secureserver.net", "port": 993, "secure": true }, "lastSyncAt": null, "lastError": null, "lastErrorAt": null, "backfillCompletedAt": null, "syncing": true, "pushActive": false, "connectedBy": "employee-id", "createdAt": "2026-11-01T09:00:00.000Z", "updatedAt": "2026-11-01T09:00:00.000Z" }
}
The first sync starts in the background; poll GET /email/accounts for status and backfillCompletedAt.
- Errors:
400invalid body;400withcodeset to a connection error code when the login fails (nothing is stored);400code: TOO_MANY_ACCOUNTS(10 mailboxes already connected);409code: ALREADY_CONNECTED(this address is already connected);403not an admin.
List Connected Mailboxes
- Method: GET
- Path:
/prod/email/accounts - Auth:
ADMIN,LEAD_TECHNICIAN - Response (200):
{ "accounts": [ …email account… ] }oldest first, withoutDISCONNECTEDaccounts.
Sync (all mailboxes, on open)
- Method: POST
- Path:
/prod/email/sync - Auth:
ADMIN,LEAD_TECHNICIAN - Body: none.
- Response (202):
{
"message": "Sync started",
"started": 1,
"accounts": [
{ "accountId": "6f1c…", "email": "office@acmeplumbing.com", "status": "ACTIVE", "result": "STARTED" },
{ "accountId": "9a2b…", "email": "sales@acmeplumbing.com", "status": "ACTIVE", "result": "RECENT" },
{ "accountId": "c3d4…", "email": "old@acmeplumbing.com", "status": "NEEDS_REAUTH", "result": "NEEDS_REAUTH" }
]
}
Call it when the conversations open and on pull-to-refresh. result per mailbox: STARTED (a sync is running in the background), RECENT (synced less than a minute ago; already fresh, nothing to do), NEEDS_REAUTH (cannot sync until reconnected). It always returns 202, with "message": "Nothing to sync" and started: 0 when no mailbox needed a run. Disconnected mailboxes are not listed. To know when the started syncs are done, poll GET /email/accounts until every account's syncing is false, then reload the messages.
- Errors:
403technician.
Sync Now (one mailbox)
- Method: POST
- Path:
/prod/email/accounts/{accountId}/sync - Auth:
ADMIN,LEAD_TECHNICIAN - Response (202):
{ "message": "Sync started", "accountId": "6f1c…" } - Errors:
404unknown or disconnected mailbox;409code: NEEDS_REAUTH(reconnect it first);429code: TOO_MANY_REQUESTSwith aRetry-Afterheader andretryAfterSecondswhen the mailbox was synced less than a minute ago (it is already fresh — not an error to show);403technician.
Rescan (one mailbox)
- Method: POST
- Path:
/prod/email/accounts/{accountId}/rescan - Auth:
ADMIN - Body: none.
- Response (202):
{ "message": "Rescan started", "accountId": "6f1c…" }
Walks the last year of the mailbox's Inbox and Sent folders again and stores every message that matches the customer list as it is now. Use it after adding an email address to a customer (or creating a customer) when their older emails should appear too. Messages already stored are recognized and never duplicated; the walk re-reads only message headers, so it is far cheaper than the first connect but still proportional to the size of the mailbox — the status is SYNCING until it completes (poll GET /email/accounts, as after connecting). The one-minute cap of Sync Now does not apply.
- Errors:
404unknown or disconnected mailbox;409code: NEEDS_REAUTH(reconnect it first);409code: SYNC_IN_PROGRESS(a sync of this mailbox is running — wait untilsyncingisfalseand try again);403not an admin.
Disconnect Mailbox
- Method: DELETE
- Path:
/prod/email/accounts/{accountId} - Auth:
ADMIN - Response (202):
{ "message": "Mailbox disconnected; synced messages are being deleted", "accountId": "6f1c…", "status": "DISCONNECTED" }
The credential is deleted immediately. Every message synced from the mailbox is deleted in the background; the account disappears from GET /email/accounts at once and from the session summary on the next login. Reconnecting the same address afterwards starts a fresh one-year backfill.
- Errors:
404unknown or already disconnected;403not an admin.
List Messages
- Method: GET
- Path:
/prod/email/messages?customerId={customerId}&limit=50&cursor={cursor} - Auth:
ADMIN,LEAD_TECHNICIAN - Query parameters:
customerId(optional — that customer's conversation across every connected mailbox, including every message in which the customer is one of several participants; without it, every stored message of the company),limit(1–200, default 50),cursor(thenextCursorof the previous page). - Response (200):
{
"messages": [ …email message list view… ],
"nextCursor": "eyJjb21wYW55SWQiOi…"
}
Newest first by receivedAt. nextCursor is null on the last page; treat it as opaque.
- Errors:
400badlimitorcursor;403technician.
Get Message
- Method: GET
- Path:
/prod/email/messages/{messageId} - Auth:
ADMIN,LEAD_TECHNICIAN - Response (200):
{ "emailMessage": { …email message with textBody and htmlUrl… } } - Errors:
404unknown message;403technician.
Update Message (link to a job, mark read)
- Method: PATCH
- Path:
/prod/email/messages/{messageId} - Auth:
ADMIN,LEAD_TECHNICIAN - Body: one or both of
{ "jobId": "job-id", "read": true }
jobId links the message to a job of the company; "jobId": null unlinks it. read: true sets readAt (kept if already set); read: false clears it. Neither changes anything in the mailbox.
- Response (200):
{ "message": "Message updated", "emailMessage": { …email message… } } - Errors:
400nothing to update, orjobId/readof the wrong type;404code: JOB_NOT_FOUNDwhen the job does not exist, or404when the message does not exist;403technician.