Tradesmen Technologies Tradesmen Technologies

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): ADMIN employees 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}): ADMIN and LEAD_TECHNICIAN employees. Technicians have no access to email; a technician receives 403 with code: 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 email and additionalEmails). 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}/rescan walks 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; customerIds lists 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

  1. 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).
  2. For a provider connected with a password or app password, the app may call POST /email/accounts/imap/test to check the settings without storing anything, then POST /email/accounts/imap to connect. The connect call tests the login again, stores the credential encrypted, and starts the first sync in the background (status: SYNCING until the one-year backfill is done, then ACTIVE).
  3. Google and Microsoft sign-in (authType OAUTH_GOOGLE / OAUTH_MICROSOFT) are reported by detection with oauthAvailable: false until 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
}
  • messageId is stable: syncing the same message again never creates a second row.
  • customerIds lists every saved customer among the participants (a shared address can match several); the message is stored once and appears in each of their conversations. primaryCustomerId is the sender for inbound mail and the first matched recipient for outbound mail.
  • threadKey groups a conversation (the first id of the message's References chain, else its In-Reply-To, else its own id); group by it to render threads.
  • messageIdHeaderHash is the same for one email seen through two connected mailboxes (one was copied on the other); de-duplicate on it when merging mailboxes.
  • attachments is metadata only: the file is not stored and there is nothing to download. size is approximate (derived from the message structure). inline: true marks a part embedded in the HTML body (an image, a signature logo); attachmentCount counts the others. Images referenced by the HTML through cid: links are therefore not available and render as missing.
  • htmlUrl is a presigned link valid for one hour. Render HTML in an isolated web view with remote images blocked by default.
  • truncated: true means a text or HTML body part was over 2 MB and was left out; the headers and the other part are intact.
  • jobId is set by PATCH /email/messages/{messageId}; readAt is 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: 400 missing or malformed email; 403 not 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 (sentFolder is the folder that will be synced as Sent, or null when the server has none), or { "ok": false, "code": "AUTH_FAILED" } with one of the connection error codes. Nothing is stored either way.
  • Errors: 400 invalid body (email syntax, empty password, bad host or port); 403 not 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: 400 invalid body; 400 with code set to a connection error code when the login fails (nothing is stored); 400 code: TOO_MANY_ACCOUNTS (10 mailboxes already connected); 409 code: ALREADY_CONNECTED (this address is already connected); 403 not an admin.

List Connected Mailboxes

  • Method: GET
  • Path: /prod/email/accounts
  • Auth: ADMIN, LEAD_TECHNICIAN
  • Response (200): { "accounts": [ …email account… ] } oldest first, without DISCONNECTED accounts.

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: 403 technician.

Sync Now (one mailbox)

  • Method: POST
  • Path: /prod/email/accounts/{accountId}/sync
  • Auth: ADMIN, LEAD_TECHNICIAN
  • Response (202): { "message": "Sync started", "accountId": "6f1c…" }
  • Errors: 404 unknown or disconnected mailbox; 409 code: NEEDS_REAUTH (reconnect it first); 429 code: TOO_MANY_REQUESTS with a Retry-After header and retryAfterSeconds when the mailbox was synced less than a minute ago (it is already fresh — not an error to show); 403 technician.

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: 404 unknown or disconnected mailbox; 409 code: NEEDS_REAUTH (reconnect it first); 409 code: SYNC_IN_PROGRESS (a sync of this mailbox is running — wait until syncing is false and try again); 403 not 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: 404 unknown or already disconnected; 403 not 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 (the nextCursor of 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: 400 bad limit or cursor; 403 technician.

Get Message

  • Method: GET
  • Path: /prod/email/messages/{messageId}
  • Auth: ADMIN, LEAD_TECHNICIAN
  • Response (200): { "emailMessage": { …email message with textBody and htmlUrl… } }
  • Errors: 404 unknown message; 403 technician.
  • 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: 400 nothing to update, or jobId / read of the wrong type; 404 code: JOB_NOT_FOUND when the job does not exist, or 404 when the message does not exist; 403 technician.