Verzenden als-adressen 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.

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. Dit is de gedeelde-inboxworkflow waarbij een klant de berichten bij de eigen provider bewaart en kopieën naar een teammailbox doorstuurt. De identiteit behoort tot de mailbox zelf en elk lid met verzendmachtiging kan deze gebruiken.

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.

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 Reply-To 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.