Adressen voor Verzenden als via API en MCP

TrekMail scheidt twee taken die verschillende aanmeldgegevens en machtigingen gebruiken:

1. Het Dashboard/Ops-oppervlak beheert herbruikbare SMTP-profielen en domeinroutering. Het gebruikt een tm_live_-token met smtp:read of smtp:write.
2. Het Webmail/Berichten-oppervlak beheert de afzenderadressen die beschikbaar zijn voor één mailbox en één gekoppelde inbox. Het gebruikt een tm_msg_-token met messages:read, messages:write of messages:send.

Deze scheiding is bewust. Een mailbox-token kan een al geautoriseerde verzendroute selecteren, maar kan geen SMTP-aanmeldgegevens onthullen of de infrastructuur van een ander account beheren.

In het kort

• Als je alleen met external_account_id verzendt, zien ontvangers het eigen adres van dat gekoppelde account en wordt de eigen SMTP-server gebruikt.
• Als je ook een brongebonden identity_id verzendt, zien ontvangers het zakelijke adres van de identiteit. TrekMail gebruikt de domeinroute of het opgeslagen SMTP-profiel dat aan die identiteit is toegewezen en bewaart daarna de kopie in Verzonden in de gekoppelde inbox.
• Starter kan dit in webmail instellen en gebruiken. Pro en Agency kunnen het ook via API of MCP automatiseren. Nano heeft geen plaatsen voor gekoppelde accounts.

De beschikbare API- en MCP-tools ontwikkelen mee met het product. Verzenden als gebruikt de SMTP- en berichtenfamilies. Elke verbinding ziet alleen de subset die het abonnement, de scopes en de goedgekeurde machtigingen toestaan.

Het routeringsmodel

Wanneer external_account_id zonder identity_id wordt verzonden, verstuurt TrekMail via de eigen SMTP-server van dat externe account en gebruikt het eigen adres.

Wanneer beide waarden worden verzonden, behandelt TrekMail het externe account als de bestemming voor inbox/Verzonden en de identiteit als het zichtbare afzenderadres + de SMTP-route:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

De identiteit en het externe account moeten aan elkaar zijn gekoppeld. Als je de bron weglaat of een identiteit uit een andere mailbox opgeeft, wordt 422 identity_unavailable geretourneerd.

1. SMTP in de Dashboard-API controleren of instellen

Gebruik een Ops-token.

Profielweergaven retourneren het wachtwoord nooit. Het gebruiks-endpoint is de veilige manier waarop een agent de gevolgen kan uitleggen voordat een gedeeld profiel wordt bewerkt of verwijderd.

MCP-tools: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. Adressen voor de exacte inbox weergeven

Gebruik een Berichten-token:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

De reactie bevat bronspecifieke identities, alle ingestelde external_identities, sending_addresses, geschikte send_as_domains, de reply_from_policy van de mailbox en, alleen voor de mailbox van de accounteigenaar, opgeslagen smtp_profiles die rechtstreeks kunnen worden geselecteerd.

MCP: roep list_identities aan met external_account_id.

Gehoste MCP tegenover lokale stdio

Berichtentools hebben één belangrijk transportverschil:

• Gehoste HTTP-MCP (OAuth): geef bij elke aanroep van een berichtentool ook mailbox_id door. De gehoste server gebruikt deze om een kortlevend berichtentoken voor precies die mailbox beschikbaar te stellen. Roep bijvoorbeeld list_identities aan met { "mailbox_id": 7, "external_account_id": 42 }.
• Zelfgehoste stdio-MCP (tm_msg_): geef mailbox_id niet door. Het statische berichtentoken is al aan één mailbox gebonden, dus het toolschema heeft alleen external_account_id nodig.

external_account_id vervangt mailbox_id nooit: het selecteert een gekoppelde inbox binnen de al geautoriseerde mailbox. SMTP-tools van het dashboard blijven accountgebonden en accepteren bij geen van beide transporten mailbox_id.

3. Een Verzenden als-identiteit maken

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email moet al het primaire adres van deze mailbox of een actieve, voor verzenden ingeschakelde alias zijn. Het domein moet actief zijn en eigendom zijn van hetzelfde account. smtp_mode: domain volgt de domeinroute die in het dashboard is ingesteld. smtp_mode: profile koppelt de identiteit vast aan smtp_connection_id; rechtstreekse profielselectie is beperkt tot de mailbox van de accounteigenaar. Lidmaatschap laat je geen gewone send_as-identiteit voor het gedeelde adres maken.

external_account_id is optioneel. De precieze betekenis is belangrijk:

• Neem deze op wanneer je de berichten van dat adres via een gekoppelde Gmail-, Outlook- of IMAP-inbox leest. De identiteit wordt dan aan die inbox gebonden en kan alleen daarmee worden gebruikt.
• Laat deze weg wanneer berichten in plaats daarvan naar een TrekMail-mailbox worden doorgestuurd.

Een persoonlijke gekoppelde inbox kan nooit aan een gedeelde mailbox worden gekoppeld: deze is privé voor de persoon die de verbinding heeft gemaakt. Laat external_account_id daar weg.

MCP: create_identity met kind=send_as. Neem op gehoste MCP de bovenliggende mailbox_id op zoals hierboven beschreven.

4. Verzenden, concept maken, plannen, beantwoorden of doorsturen

De gewone berichtbewerkingen accepteren hetzelfde bronpaar:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id wordt ondersteund bij direct verzenden, concept opslaan/bijwerken en gepland verzenden. Voorbereiding van antwoorden/doorsturen accepteert external_account_id en selecteert de passende identiteit uit de bezorgingsheaders. De geselecteerde identiteit wordt opnieuw geautoriseerd wanneer een bericht in de wachtrij daadwerkelijk wordt uitgevoerd. Als de alias, het domein, het profiel of het gekoppelde account wordt uitgeschakeld, stopt de bezorging in plaats van ongemerkt op een ander afzenderadres terug te vallen.

MCP-tools: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all en prepare_forward.

Verzenden als gedeelde mailbox

Om vanuit de gedeelde inbox te versturen via Message API of MCP heeft het lid Lezen en Verzenden als nodig. Gebruik diens token met shared_mailbox_id. Een token voor de gedeelde mailbox kan lezen, maar niet versturen.

{
  "shared_mailbox_id": 5,
  "to": ["customer@example.net"],
  "subject": "Re: your order",
  "body": { "text": "Answered by the team" }
}

Het token blijft aan het lid gebonden, en het auditspoor ook: een verzending vanaf het teamadres legt vast wie hem deed. GET /messages/identities?shared_mailbox_id=5 toont de adressen waarvandaan die mailbox mag verzenden.

Twee weigeringen om rekening mee te houden:

• shared_mailbox_not_a_sender (403): het token hoort zelf bij een gedeelde mailbox. Lezen blijft ongemoeid; alleen verzenden vereist een lid.
• shared_mailbox_send_denied (403): Het lid heeft Lezen en Verzenden als nodig.

Teamadressen uit persoonlijke webmail worden niet vermeld of geaccepteerd als Message API-identiteiten. Een geweigerde identity_id geeft 422 identity_unavailable; wijzigen of verwijderen van een teamadres geeft 422 identity_delegated. Deze antwoorden bevatten hint en identity_id, met shared_mailbox_id en member_id indien beschikbaar. Een geweigerde gedeelde verzending bevat shared_mailbox_id en, bij een lid met alleen verzendrecht, member_id. Lees de aanwijzing voordat je opnieuw probeert. Zonder gedeelde context of identiteit verzend je vanaf een ander adres.

Message API kan met shared_mailbox_id een bericht plannen voor leden met het recht ‘Lezen’ en Verzenden als. Webmail biedt gepland versturen binnen een gedeelde inbox niet aan. Gebruik voor lijsten, opnieuw plannen of annuleren dezelfde shared_mailbox_id; de rijen horen bij de gedeelde mailbox. De rij zelf noemt niet wie het bericht heeft gepland.

MCP: send_message, schedule_message en list_identities accepteren shared_mailbox_id. Op gehoste MCP blijft mailbox_id het lid.

Antwoordbeleid

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient antwoordt waar mogelijk vanaf het adres dat het bericht heeft ontvangen. default begint voor normale mailboxberichten altijd met de mailboxstandaard. MCP gebruikt set_reply_from_policy.

Veiligheids- en isolatieregels

• SMTP-aanmeldgegevens komen nooit in de reactie van de Berichten-API of MCP terecht.
• Elk extern account en elke identiteit is beperkt tot de mailbox van het berichtentoken.
• Een gekoppelde Verzenden als-identiteit kan alleen met de exacte external_account_id worden gebruikt; een identiteit die bij de mailbox hoort, alleen zonder deze waarde.
• Het afzenderadres moet al zijn geautoriseerd als mailboxadres of voor verzenden ingeschakelde alias; de API kan geen willekeurige afzenderadressen bedenken.
• Voor het maken is een werkende route vereist en deze wordt bij de bezorging opnieuw gecontroleerd.
• Aangepaste Reply-To-headers mogen niet conflicteren met de opgeslagen waarde in het veld Antwoord aan van een identiteit.
• Wijzigingen aan identiteiten en profielen via MCP vereisen de juiste schrijfmachtiging. Een lokaal gehoste MCP-beheerder kan expliciete goedkeuring voor schrijfacties vereisen; voor verzenden is ook een bevestiging per bericht nodig.

Er zijn geen nieuwe tekenreeksen voor tokenscopes nodig. Bestaande smtp:*- en messages:*-tokens blijven volgens hun huidige machtigingen werken.

Welke verzendlimiet geldt?

API-aanroepen behouden ook hun eigen bescherming tegen misbruik: standaard 60 verzendaanvragen per minuut per berichtentoken en 100 API-verzendingen per dag voor de hele mailbox. Deze gelden ongeacht welke server de e-mail uiteindelijk bezorgt.