Inbox & notifications

These endpoints answer "did the customer reply?", "what's waiting on me?" and "what did the team do today?". They read what TruTec already has; none of them sends anything.

They work as the person who created the API key (a partner key acts as the workspace owner): you see the email that person can see in TruTec, and their notifications and mentions.

Emails#

The Emails page in TruTec puts every customer email in one list:

• Sent: proposals, signature requests, invoices, schedule and warranty notices, automatic follow-ups, campaigns and emails people wrote, from a connected mailbox or TruTec's own sender. Internal mail (mailbox tests, owner reviews) is left out.
• Received: customer replies TruTec filed on jobs.

A received email needs a reply until someone emails that address back or ticks it handled (answered by phone, nothing to answer). Automatic follow-ups don't count as an answer.

Someone limited to their own (or assigned) jobs sees the email on those jobs plus anything they sent; owners and people who see every job see everything.

The email object#

Field	Type	Description
id	integer	Unique within its direction. Use both to read it: GET /v1/emails/{direction}/{id}.
direction	string	sent or received.
at	string	When it was sent or arrived (UTC).
subject, snippet	string	snippet is the first line of what was written, when TruTec has it.
from, to, cc		from is {name, email}; to and cc are addresses.
contact_name	string	The customer contact, when the address belongs to one.
type, type_group	string	A plain label (Proposal, Automatic follow-up, Reply) and, for sent email, the filter value (proposal, follow_up, ...).
automatic	boolean	An automatic follow-up.
job, company	object	{id, name} when known.
attachments	array	File names.
sent_by	object	Sent email: {id, name} of the person.
status	string	Received email: needs_reply, answered or handled.
needs_reply, overdue	boolean	overdue once it has waited more than 24 hours.
answered_at, handled_at, handled_by		When it was answered (the first email to that address after it), or ticked handled and by whom.
in_reply_to_email_id	integer	Received email: the sent email it answers, when known.

List emails#

GET /v1/emails

Permission: Read jobs

Newest first.

Name	Type	Required	Description
direction	string	No	all (default), sent or received.
needs_reply	boolean	No	Only customer email still waiting on you, from the last 60 days.
job_id	integer	No	Only email about this job.
type	string	No	Sent email kind: proposal, signature, signed, email, follow_up, campaign, quote_request, quote_accepted, schedule, warranty, agreement, invoice.
include_automatic	boolean	No	false hides automatic follow-ups.
mine	boolean	No	Only mail you sent, or on jobs you own.
q	string	No	Search sender, recipient, subject, job or company.
limit, offset	integer	No	Default 50, maximum 200.

curl "https://trutec.ai/api/v1/emails?job_id=70412&direction=received" \
  -H "X-API-Key: sk_your_api_key_here"

{
  "data": [
    {
      "id": 88213,
      "direction": "received",
      "at": "2026-10-12T18:22:05Z",
      "subject": "Re: Proposal for Northgate Plaza reseal",
      "snippet": "Looks good. Can you start the week of the 3rd?",
      "from": { "name": "Pat Lee", "email": "[email protected]" },
      "to": ["[email protected]"],
      "contact_name": "Pat Lee",
      "type": "Reply",
      "job": { "id": 70412, "name": "Northgate Plaza reseal" },
      "company": { "id": 5120, "name": "Northgate Properties" },
      "status": "needs_reply",
      "needs_reply": true,
      "overdue": false,
      "in_reply_to_email_id": 77120
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0 }
}

Get an email and its conversation#

GET /v1/emails/{direction}/{id}

Permission: Read jobs

The email plus every email to or from the same person with the same subject (Re: and Fwd: ignored) within 120 days, oldest first, up to 40 (earlier_count says how many older ones were left out). Each message has body (the words TruTec kept) and body_state:

body_state	Meaning
ready	body is the whole email.
fetch	Only part was kept; read the whole email with the body endpoint below.
reconnect	It's in a mailbox that needs reconnecting in TruTec.
preview	Only the start of a reply was kept and no mailbox can supply more.
none	Sent before TruTec kept copies of emails.

reply_to names who to answer and a Re: subject.

Read a whole email#

GET /v1/emails/{direction}/{id}/body

Permission: Read jobs

Reads the email from the workspace's connected mailbox the first time (TruTec keeps it after that), like opening it in the email window. state is ready with text and display-safe html, or unavailable with a reason (reconnect, gone, busy, error) and a message.

Mark an email handled#

POST /v1/emails/received/{id}/mark-handled

Permission: Write jobs

Ticks a received email handled so it leaves Needs reply. Send {"handled": false} to put it back. Returns the email.

Mark many emails handled#

POST /v1/emails/mark-handled

Permission: Write jobs

{"email_ids": [88213, 88240], "handled": true}, up to 500 received email ids. Every id must be a received email the key's creator can see; otherwise nothing changes and the 404 lists the ids.

Notifications#

The bell in TruTec: schedule changes, crew and customer messages, field alerts and reminders such as a warranty packet waiting to be sent. They come with scheduling and crews; a workspace without them gets 403. Mentions in team notes are separate (below).

Field	Type	Description
id	integer
kind, title, body	string
link	string	Where it points in TruTec.
read, read_at, created_at

List notifications#

GET /v1/notifications

Permission: Read jobs

Newest first. unread=true for unread only. limit, offset. The response also has unread, the unread count.

Mark a notification read#

POST /v1/notifications/{id}/mark-read

Permission: Write jobs

Mark all notifications read#

POST /v1/notifications/mark-all-read

Permission: Write jobs

Mentions#

Team notes where someone tagged the key's creator, as in the Mentions inbox. Office members only (403 otherwise).

Field	Type	Description
id	integer
read	boolean
job	object	{id, name}.
scope	string	Job, or the service or visit the note is about.
note_id	integer	The note.
author	object	{id, name}.
content, created_at, link

List mentions#

GET /v1/mentions

Permission: Read jobs

Newest first. unread=true for unread only. The response also has unread.

Mark a mention read#

POST /v1/mentions/{id}/mark-read

Permission: Write jobs

Daily Summary#

Get the daily summary#

GET /v1/daily-summary

Permission: Read jobs

The dashboard's Daily Summary card: what happened in a local period, counted and listed. Jobs are fenced to what the key's creator can see.

Name	Type	Required	Description
period	string	No	today (default), yesterday, week (from Monday) or month.
who	string	No	team (default), me (only what the key's creator did) or members (with member_ids).
member_ids	string	No	Comma-separated user ids, with who=members.
scope	string	No	all (default) or mine (only jobs the key's creator owns).
timezone	string	No	IANA zone for the day boundaries, e.g. America/Chicago. Default: the workspace's.

counts has new_leads, status_changes, emails, calls, won, lost, site_visits, followups and takeoff_minutes. items lists up to 100 activities, newest first, each with kind, local time, who, text, detail and link. For week and month, people has the same counts per person.

{
  "data": {
    "period": "today",
    "period_label": "Today",
    "date_label": "Tue, Oct 13",
    "timezone": "America/Chicago",
    "who": "team",
    "counts": { "new_leads": 3, "status_changes": 5, "emails": 12, "calls": 7, "won": 1, "lost": 0,
                "site_visits": 2, "followups": 4, "takeoff_minutes": 95 },
    "items": [
      { "kind": "won", "time": "2:05 PM", "who": "Office Manager",
        "text": "Status: Proposal Sent → Won · Northgate Plaza reseal", "detail": null,
        "link": "https://trutec.ai/jobs/70412" }
    ],
    "has_activity": true
  }
}

Errors: 400 a bad filter value; 403 missing permission, the key's creator is no longer in the workspace, or the feature isn't available to them; 404 an id that isn't in this workspace or that the key's creator can't see.