Core concepts

Labels

Labels mark state on messages and threads. Five are set by Goshen Email; the rest are yours.

System labels

Label	Set when
`received`	The message arrived from outside.
`sent`	The inbox sent the message.
`unread`	The message arrived and nobody has removed the label yet.
`trash`	The message or thread was moved to Trash. Trashed mail is hidden from lists unless you ask for it.
`quarantined`	The scanner held the message. Only a person can release it from the dashboard. See Quarantine.

quarantined is the one label no API key can add or remove; the request fails with quarantine_review_required. received and sent are set by Goshen Email when mail arrives or leaves. The API does not stop you from removing them, but the dashboard's Inbox and Sent views depend on them, so leave them alone. unread and trash are meant to be changed.

Your labels

Any other label is yours to define. Labels are 1 to 64 characters. A message can carry up to 50 labels when sent. Typical uses:

Workflow state. needs-human, awaiting-vendor, done.
Campaign or task. q3-outreach, ticket-4821.
Classification your agent made. invoice, newsletter, spam-suspect.

Labels are free text, so decide on a vocabulary before your agents start inventing their own.

Adding and removing labels

On a message:

curl "https://api.goshenemail.com/v1/inboxes/research%40agents.goshenemail.com/messages/%3Cid%40example.net%3E/labels" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY" -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"addLabels":["invoice","needs-human"],"removeLabels":["unread"]}'

On a thread, PATCH /v1/inboxes/{inboxId}/threads/{threadId}/labels takes the same body and applies to every message in the thread.

Both operations need the messages:write scope. They return an empty 200 on success.

Labels on outgoing mail

send and reply accept a labels array so a message is tagged from the moment it leaves. The sent label is added regardless.

Filtering by label

listMessages and listThreads take labels as a repeated query parameter and return items that carry every label given:

curl "https://api.goshenemail.com/v1/inboxes/research%40agents.goshenemail.com/messages?labels=received&labels=invoice" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY"

In the dashboard

The dashboard shows labels on each conversation and lets you add or remove them, move mail to Trash, and mark it read. Inbox, Sent, All mail, Quarantine, and Trash are views over these labels, not separate folders.