Connecting marketplace and mailbox to the sales agent

A dealer answers enquiries in three places: in the marketplace inbox, in their own mail client and on the website. Three surfaces mean three answer qualities, three response times and the recurring situation of two colleagues answering the same enquiry differently.

A channel is the connection to exactly one source and carries its own profile and its own credentials. The separation is what matters: credentials can be revoked without deleting the channel — the history stays, the access ends.

What this case requires

• One profile per channel. Marketplace and mailbox may answer differently; the profile decides tone and permissions.
• A dedicated mailbox for the agent. A shared mailbox leads to agent and human taking messages away from each other.
• An account at the marketplace whose holder can consent. The account holder grants consent themselves, not us — it cannot be substituted.
• Monitoring of the channel state. A channel whose mailbox has been rejecting for three days is only noticed if somebody looks.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Create the channel. POST /agent/channels requires type, name and profileId and takes settings. For a mailbox that includes imap and smtp — host, port and username, but no password. That is deliberate: secrets take their own route.
2. Obtain the marketplace’s consent. POST /agent/channels/{channelId}/ebay/consent returns an authorizeUrl. The account holder grants consent there, and the return runs through the designated return path. Marketplace credentials are never typed in.
3. Store the mailbox secrets. PUT /agent/channels/{channelId}/mail/credentials accepts the passwords and answers with imapStored and smtpStored. No password comes back: according to the contract, passwords go straight into encrypted storage, are never logged and are never part of the channel settings.
4. Test the mailbox. POST /agent/channels/{channelId}/mail/test logs in for reading, selects the folder and, for sending, goes as far as login; nothing is sent. This stage belongs before operation, not after: otherwise a wrong password only surfaces when a customer is waiting for a reply.
5. Watch the state. GET /agent/channels/{channelId}/status returns nextPollAt, errorCount, lastErrorCode, pendingEvents and pendingOutbound. That is where monitoring attaches — to figures, not to guesses.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"returnUrl":"https://example.de/agent/einwilligung-fertig"}' \
  'https://api.tapinomahub.com/hub/index.php/agent/channels/<channelId>/ebay/consent'

What you end up with

In the end marketplace, mailbox and website answer with the same quality, and each channel can be stopped, tested or revoked individually without touching the others.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-agent). All use cases arranged by surface and role: overview of the use cases.