Choose where an address delivers its mail

At the end of this guide each of your addresses delivers to the right place: tickets, the shared inbox, or one person's inbox.

The three places mail can land

	Tickets	Shared inbox	Personal inbox
Use it for	Customer support	Team mail that is not a support request: partners, suppliers, billing	One member's own mail
Who sees it	Every member	Every member	Only its owner
A thread is called	A ticket	A conversation	A conversation
Status	`open`, `in_progress`, `pending`, `closed`	`open`, `closed`	`open`, `closed`
Priority and SLA	Yes	No	No
Address setting	`purpose: ticket`	`purpose: inbox`, no `user_id`	`purpose: inbox` with a `user_id`

All three share the workspace's tags, contacts, drafts, summaries and internal notes. The tickets guide covers the ticket fields.

How an address gets its purpose

Every address in a workspace has a purpose. New mail to the address goes where the purpose says. A reply to an existing thread always goes back to that thread, whatever the address is set to now.

An address is personal when it has purpose inbox and a user_id: the member whose inbox it is. An address with a user_id must keep purpose inbox.

What you need first

To be an owner of the workspace. Only owners manage addresses and workspace settings.
At least one address in the workspace. To add one on your own domain, follow the custom domain guide.
For the API requests: an API token with the write ability.

Steps

List your addresses. In the dashboard open Settings → Emails. Each address shows its purpose as Ticket, Shared or Inbox. Over the API, add ?purpose=inbox or ?purpose=ticket to filter:
```
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails
```

Make an address a shared inbox. In the dashboard, edit the address and choose Shared. Over the API:

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": "inbox", "user_id": null }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails/EMAIL_ID

Or give it to one person. Choose Inbox and pick the member. Over the API, send the member's user id:

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": "inbox", "user_id": 12 }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails/EMAIL_ID

Or turn it back into a ticket address. Clear the owner in the same request:

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": "ticket", "user_id": null }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/emails/EMAIL_ID

Switch off what the workspace does not use. In Settings → General an owner can turn Tickets, Shared Inbox and Personal Inbox on or off. At least one stays on. Requests to a switched-off part answer 403.

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tickets_enabled": true, "shared_inbox_enabled": true, "personal_inbox_enabled": false }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID

Start a thread yourself. Mail does not have to come in first. This sends a new email from the shared inbox; POST …/personal-inbox takes the same fields and sends from your own inbox.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Invoice for October",
    "body": "Hi Sam, the October invoice is attached to this thread.",
    "workspace_email": "[email protected]"
  }' \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/conversations

A shared conversation can only be sent from a shared address, and a personal one only from its owner's own address.

Check that it worked

Send a test email to the address from outside PimiDesk. It shows up under Tickets, Shared Inbox or Inbox in the sidebar, usually within a minute. Over the API:

# Shared inbox
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/conversations

# Your own personal inbox
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://desk-api.pimi.io/api/v1/workspaces/WORKSPACE_ID/personal-inbox

Good to know

Your sidebar is yours. Each member can hide Tickets, Shared Inbox or Inbox from their own sidebar under Settings → Sidebar. Nobody else's view changes.
When a member leaves. Their personal inbox is not handed to the team. Workspace owners can read it as an archive; nobody can reply from it.
Webhooks. Conversation events fire for both inboxes. owner_id is null for a shared conversation and the owner's user id for a personal one. See the webhooks guide.

What goes wrong

What you see	Why
Mail to a new shared address still opens tickets	The address still has purpose `ticket`. Check it in step 1.
`422` on changing the purpose	The address has an owner. Send `"user_id": null` in the same request.
`403` "feature is not enabled"	That part is switched off for the workspace (step 5).
`403` on starting a thread	The workspace is on trial. A trial workspace can reply to people who wrote in, and cannot start a thread.
A reply lands in the old place after a purpose change	Expected. Replies follow their thread; only new mail follows the new purpose.

Add your own domain: send and receive on addresses at your domain
Work a ticket from open to closed
Email pipeline: what happens to a message between arriving and showing up