Contacts

A contact is a person who has written to one of your mailboxes. Contacts are created by incoming mail, not by hand: the first message from an address creates the contact, and every later message from that address, to any of your mailboxes, is filed under it. That is what lets the inbox group a customer's threads together.

How a contact is built

• Identity. Each email address a contact has used is an identity on the contact. The first one seen is the primary.
• Name. Taken from the sender's display name on their first message, and filled in later if it was missing. You can edit it on the contact page.
• Organisation. Derived from the sender's domain: dana@arboretum.co belongs to Arboretum. Contacts from the same domain share an organisation, and the Customer grouping in the inbox groups by it. Addresses at large consumer providers are not grouped this way.
• Counts and dates. Messages received from the contact, first seen, last seen.

Mail classified as junk does not create or update a contact. Marking a message as Not junk in the inbox does.

The contacts list

Contacts lists every contact in the workspace with name, company, message count, last seen, and, when linked, plan and monthly revenue. The list can be searched and sorted by name, message count, last seen or revenue. Clicking a row opens the contact page.

The contact page

• Writes from: every address the contact has used, and whether it was seen in incoming mail.
• In your app: the record you linked through the API, if any (below).
• Notes: free text about the contact, kept on the contact rather than on a thread. Saved with Save notes and shown in the customer panel beside every conversation with them.
• Conversations: every thread with this contact, newest first, each linking into the inbox.

Linking your own customer record

If your product has customers, you can attach your record of a customer to the contact so it is visible beside their mail. The link carries a user id, a plan name, a monthly revenue figure, a sign-up date, an optional display name, and free-form attributes (a JSON object of anything else worth showing, such as seats or region). It is written through the REST API:

PUT https://api.foundermail.mx/contacts/dana@arboretum.co/link
X-Api-Key: <key with config:write>
Content-Type: application/json

{
  "externalUserId": "usr_8Kd21",
  "plan": "Pro",
  "monthlyRevenue": 290,
  "signedUpAt": "2025-03-14T09:00:00Z",
  "attributes": "{\"Seats\":\"12\",\"Region\":\"EU\"}"
}

DELETE on the same URL removes the link. Linking an address that has never written to you creates the contact, so the record is in place when they do. The response says whether the contact already existed. Details in the REST API.

Deleting a contact

Contacts are not deleted from the dashboard. Deleting the conversations with a contact removes the mail; the contact record, with its addresses and notes, remains so that a future message from them is filed correctly. To have personal data removed, write to support.