App-wachtwoorden voor mail via API en MCP

De REST API en MCP kunnen app-wachtwoorden van een gewone mailbox weergeven, maken, vervangen en intrekken, de aanmeldingsmodus voor mail-apps wijzigen en de accountstandaard voor toekomstige mailboxen instellen. Deze pagina is de referentie voor integraties. Zie App-wachtwoorden voor mail op je apparaten voor dashboard- en webmailinstructies.

Een app-wachtwoord opent IMAP, SMTP op poorten 465 en 587, ManageSieve en CalDAV/CardDAV. Het opent nooit de nieuwe webmail of het dashboard. Klassieke webmail meldt aan via IMAP en accepteert app-wachtwoorden. Mailbox-2FA beschermt alleen de aanmelding bij de nieuwe webmail; mail-apps en klassieke webmail vragen nooit om die code.

Deze functie heeft geen afzonderlijke abonnementseis voor mailboxen. De bestaande abonnementsrechten voor API en MCP blijven gelden; zie API-bereiken en machtigingen.

Verificatie, bereiken en machtigingen van leden

Gebruik een Bearer-token voor REST-verzoeken onder /api/v1. JSON-schrijfacties gebruiken Content-Type: application/json en een Idempotency-Key-header.

De machtiging voor het instellen van wachtwoorden wordt gecontroleerd op de rol van het lid, naast het API-bereik van het token. Dit geldt voor ledentokens en door leden geautoriseerde connectors. Het token van een eigenaar heeft geen extra bereik nodig voor het instellen van wachtwoorden. Een ontbrekende machtiging voor het lid geeft 403 scope_blocked_by_membership terug.

Gehoste OAuth-connectors kunnen de bijbehorende REST-capaciteitsbereiken gebruiken. Bij de oudere bundels levert mail:read de bereiken mailboxes:read en account:read; mail:write levert ook mailboxes:write. Uitbreiding van bereiken omzeilt nooit de regels voor ledenmachtigingen of acties die alleen de eigenaar mag uitvoeren.

De tokenbeperkingen domain_ids en mailbox_ids gelden ook voor bulkselecties. De app-wachtwoordendpoints en beide modusendpoints geven 404 not_found terug als de functie uit staat, na verificatie en middlewarecontroles. Een ontoegankelijke of ontbrekende mailbox geeft ook 404 terug, dus lees niet elke 404 als een signaal over de functiestatus.

Endpoints in één overzicht

De onderstaande paden bevatten het voorvoegsel /api/v1. {mailbox} is de ID van de gewone mailbox; {id} is de ID van een bijbehorende app-wachtwoordvermelding.

Alle schrijfacties in deze tabel vereisen Idempotency-Key. Het wachtwoordendpoint is een bestaande resetbewerking voor beheerders, los van app-wachtwoordrotatie.

App-wachtwoorden weergeven en velden begrijpen

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

Het antwoord bevat op het hoogste niveau mailbox_id, client_auth_mode, limit, active_count en data, een array van vermeldingen. limit is 25 actieve wachtwoorden per mailbox. Actieve vermeldingen staan eerst, met de nieuwste bovenaan; ingetrokken vermeldingen blijven 90 dagen zichtbaar. Geen enkel lijstantwoord bevat een geheim.

Elke vermelding bevat:

Openbare intrekredenen zijn revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared en mailbox_trashed. De lijst bevat geen intern door het platform aangemaakte inloggegevens.

Een app-wachtwoord maken

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name is verplicht: 1 tot 64 afdrukbare tekens. Reeksen witruimte worden teruggebracht tot één spatie. De mailbox moet een actieve gewone mailbox zijn waarvan de aanmelding niet is opgeschort, met minder dan 25 actieve app-wachtwoorden.

Het 201-antwoord bevat de volledige vermelding onder data, voegt data.password toe en bevat message. Dit zijn bijvoorbeeld de velden voor de inloggegevens binnen dat antwoord:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

Dit voorbeeld laat de andere hierboven beschreven velden weg. Het voorbeeldgeheim is ter illustratie. Een echt geheim bestaat uit 16 gegenereerde kleine letters en wordt zonder spaties teruggegeven. Apps accepteren ook spaties en hoofdletters; toon het in vier groepen van vier als je het aan een gebruiker presenteert.

Het wachtwoord wordt maar één keer teruggegeven. Houd het buiten applicatielogs. De gebruiker voert het rechtstreeks in de mail-app in met het volledige mailboxadres als gebruikersnaam. Bij maken en vervangen wordt een melding met de naam van het app-wachtwoord naar de mailbox en het hersteladres gestuurd, als dat is ingesteld, zonder het geheim. Het eerste app-wachtwoord dat met een nieuwe mailbox wordt uitgegeven, is de uitzondering (zie hieronder).

Gebruik de API voor mailclientconfiguratie voor de verbindingsinstellingen. Een gedownload Apple-profiel bevat geen wachtwoord; de gebruiker voert het app-wachtwoord in wanneer macOS of iOS er tijdens de installatie om vraagt.

Het eerste app-wachtwoord krijgen met een nieuwe mailbox

POST /api/v1/mailboxes en POST /api/v1/mailboxes:bulk accepteren een optionele boolean create_app_password. Met true krijgt elke gemaakte mailbox ook het eerste app-wachtwoord, dat één keer wordt teruggegeven als app_password: de hierboven beschreven velden plus password. Het heet Created with the mailbox, en er wordt geen e-mailmelding voor verstuurd, omdat de mailbox nieuw is en de aanroeper net het wachtwoord heeft ontvangen. Zonder het veld (standaard false) blijft het antwoord ongewijzigd. Het wordt genegeerd zolang app-wachtwoorden niet zijn ingeschakeld.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

Het 201-antwoord bevat dan one_time_password, het mailboxwachtwoord voor webmail, en app_password.password voor mail-apps. In een bulkantwoord heeft elke gemaakte rij een eigen app_password. Als het niet kon worden uitgegeven, is app_password gelijk aan null (een enkele aanmaak voegt ook _app_password_warning toe); de mailbox wordt toch gemaakt en je kunt er een maken met het endpoint hierboven. Een exacte herhaling van een enkele aanmaak met dezelfde Idempotency-Key geeft hetzelfde antwoord terug, inclusief beide geheimen, zonder een tweede app-wachtwoord uit te geven. Een herhaalde bulkaanvraag laat de geheimen weg, net als bij one_time_password.

Een wachtwoord vervangen of intrekken

Vervangen vereist geen JSON-body:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

Het 200-antwoord bevat de nieuwe volledige vermelding onder data, het eenmalige data.password, op het hoogste niveau replaced_id voor de oude vermelding en message. De vervanging heeft een nieuw data.id en dezelfde naam. De oude vermelding wordt ingetrokken met revoked_reason: "rotated", het geheim werkt meteen niet meer en apps die het gebruiken worden afgemeld. Werk het apparaat bij met het vervangende wachtwoord.

Intrekken zonder vervanging:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Er is geen body nodig. Het 200-antwoord bevat status: "revoked" en de volledige ingetrokken vermelding onder data. De app verliest toegang; andere apparaten met geldige app-wachtwoorden maken zelf opnieuw verbinding. Intrekken kan niet ongedaan worden gemaakt. Een al ingetrokken vermelding met een nieuw verzoek proberen te vervangen of in te trekken geeft 409 conflict terug.

De aanmeldingsmodus voor mail-apps van één mailbox wijzigen

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode is verplicht en accepteert:

• app_password_only: mail-apps vereisen een app-wachtwoord. Verbindingen met het mailboxwachtwoord worden afgemeld; apps met een geldig app-wachtwoord maken zelf opnieuw verbinding.
• password_or_app_password: mail-apps accepteren het mailboxwachtwoord of een app-wachtwoord.

Het 200-antwoord bevat mailbox_id, client_auth_mode en message. De huidige modus opnieuw instellen geeft 200 terug en verandert niets. Een modus wijzigen trekt bestaande app-wachtwoorden niet in.

Maak wachtwoorden voor de apparaten voordat je ze verplicht stelt. Een geweigerde aanmelding met het mailboxwachtwoord kan deze melding geven: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Aanmelden mislukt. Deze mailbox accepteert alleen app-wachtwoorden: maak er een in webmail onder Instellingen > App-wachtwoorden.). Sommige apps tonen alleen een algemene wachtwoordfout.

Gedeelde mailboxen hebben geen rechtstreekse aanmelding en geven op dit endpoint 422 mailbox_not_eligible terug. Systeemmailboxen van het platform kunnen niet naar app_password_only worden omgezet; dat geeft 422 system_mailbox_protected terug.

Geen van beide modi verandert de aanmelding bij de nieuwe webmail, Alle postvakken IN, Message API-tokens, migraties naar de mailbox, mailregels of doorsturen. Leden van gedeelde mailboxen gebruiken de inloggegevens en modus van hun eigen gewone mailbox.

Modi in bulk wijzigen

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Geef mode en precies één selectiecriterium op:

Account- en tokenbeperkingen verkleinen elke selectie. Een expliciete ID buiten het toegangsbereik of een onbekende ID geeft 404 terug in plaats van een gedeeltelijke selectie toe te passen. Een onbekend domein of een domein van een ander account geeft 422 validation_error terug. Geen of meerdere selectiecriteria geven 422 invalid_selection terug.

Er mogen maximaal 1000 mailboxen overeenkomen. Een grotere selectie geeft 422 selection_too_large terug voordat iets wordt gewijzigd. Beperk de selectie binnen het domein of stuur expliciete batches.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched telt geselecteerde mailboxen; updated telt daadwerkelijke moduswijzigingen; skipped telt gedeelde mailboxen, mailboxen in de prullenbak of mailboxen die worden verwijderd, plus systeemmailboxen van het platform wanneer app-wachtwoorden worden verplicht. Gepauzeerde mailboxen en mailboxen waarvan de aanmelding is opgeschort kunnen hun modus laten bijwerken voor wanneer toegang terugkomt. Mailboxen die al de gevraagde modus hebben, tellen als matched maar niet als updated of skipped, dus de bewerking is veilig te herhalen. Opgeschorte accounts worden geweigerd met 403.

Mailboxstatus lezen en de accountstandaard instellen

Wanneer app-wachtwoorden aan staan, bevatten GET /api/v1/mailboxes en GET /api/v1/mailboxes/{mailbox} deze velden in mailboxresources:

• client_auth_mode: app_password_only of password_or_app_password.
• app_passwords_count: geheel getal voor het aantal actieve zichtbare app-wachtwoorden, zonder interne platformreferenties.

Beide velden worden weggelaten als de functie uit staat. Gedeelde mailboxen hebben geen bruikbare rechtstreekse aanmeldingsmodus of app-wachtwoorden; vraag in plaats daarvan de inloggegevens van een gewone mailbox van een lid op.

GET /api/v1/account vereist account:read. De normale velden op het hoogste niveau blijven beschikbaar: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits en created_at. Het voegt new_mailbox_client_auth_mode alleen toe als app-wachtwoorden aan staan en het platform de accountstandaard toepast op nieuwe mailboxen. Anders blijft GET beschikbaar en laat het dat veld weg.

Alleen de accounteigenaar kan de standaard wijzigen:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

Het verplichte veld accepteert dezelfde twee modi. Dit is hier het enige schrijfbare accountveld. Het antwoord bevat op het hoogste niveau id, new_mailbox_client_auth_mode en message. PATCH geeft 404 terug tenzij aan beide voorwaarden voor het tonen van het veld is voldaan, en 403 scope_blocked_by_membership voor elk ledentoken of elke door een lid geautoriseerde connector.

Een eigenaarstoken dat door domain_ids of mailbox_ids is beperkt, geeft 403 token_resource_constrained terug. Gebruik een eigenaarstoken zonder resourcebeperkingen of wijzig de standaard in de accountinstellingen.

De standaard geldt voor toekomstige mailboxen die via het dashboard, in bulk, via uitnodigingen, de API of agents worden gemaakt. Bestaande mailboxen veranderen nooit. Bij het maken van één mailbox via de API kan client_auth_mode expliciet worden opgegeven in POST /api/v1/mailboxes; weglaten volgt de accountstandaard. Bestaande mailboxen houden bij de uitrol password_or_app_password. De standaard voor nieuwe mailboxen is app_password_only, tenzij de accounteigenaar dit wijzigt.

Een mailboxwachtwoordreset trekt app-wachtwoorden automatisch in

POST /api/v1/mailboxes/{mailbox}/password vereist mailboxes:write, dezelfde machtiging voor het instellen van wachtwoorden voor leden en Idempotency-Key. De body vereist password, het nieuwe mailboxwachtwoord, volgens het mailboxwachtwoordbeleid. Dit is geen endpoint voor het maken van app-wachtwoorden.

Elke geslaagde reset door een beheerder via dit endpoint, ook een wachtwoordwijziging door een MCP-agent, trekt alle app-wachtwoorden in met reden mailbox_password_reset. Er is geen optie om dit over te slaan. Wanneer de functie aan staat, bevat het antwoord app_passwords_revoked, een geheel getal, naast status, sync_pending en message:

• 200, status: "updated", sync_pending: false als de synchronisatie met de mailserver is voltooid.
• 202, status: "update_pending", sync_pending: true als het wachtwoord is opgeslagen en synchronisatie nog in behandeling is. App-wachtwoorden zijn op dat moment al ingetrokken.

De reset trekt ook bestaande berichttokens van de mailbox in. Dit is een gevolg van het opnieuw instellen van het mailboxwachtwoord, niet van het roteren van één app-wachtwoord of het wijzigen van de mail-appmodus.

Eigen wachtwoordwijzigingen in webmail trekken app-wachtwoorden alleen in als de gebruiker Ook alle app-wachtwoorden intrekken selecteert. Wachtwoordherstel, opschorting van de aanmelding, omzetting naar een gedeelde mailbox en verplaatsing naar Onlangs verwijderd trekken ze allemaal in. Toegang of de mailbox herstellen brengt ingetrokken geheimen niet terug. Zie Aanmelding bij mailbox opschorten via API.

Idempotentie en eenmalige geheimen

Gebruik een nieuwe Idempotency-Key voor elke bedoelde schrijfactie en hergebruik die alleen als hetzelfde verzoek met dezelfde methode, hetzelfde pad en dezelfde body na een transportfout opnieuw wordt geprobeerd. Sleutels zijn verplicht en mogen maximaal 255 tekens bevatten. Geslaagde antwoorden worden gedurende het standaardvenster van 24 uur gecachet; een sleutel voor een ander verzoek hergebruiken geeft 409 idempotency_mismatch terug.

Een herhaling van het maken of roteren van een app-wachtwoord geeft dezelfde veilige identificatoren terug maar laat data.password weg. Het antwoord bevat _idempotency_replay_warning en de header X-Idempotency-Replayed: true. Een herhaling kan een verloren geheim niet herstellen. Gebruik het teruggegeven data.id om de actieve vermelding met een nieuwe sleutel te roteren en een bruikbare vervanging te krijgen. Houd de nieuwe ID na rotatie bij.

Een geslaagde intrekking met dezelfde sleutel herhalen geeft het opgeslagen resultaat terug. Een nieuw intrekverzoek voor die al ingetrokken vermelding geeft 409 conflict terug. Moduswijzigingen zijn van nature herhaalbaar, maar geef elke bedoelde wijziging een nieuwe sleutel: een eerdere sleutel hergebruiken na een moduswijziging kan een oud antwoord herhalen in plaats van de nieuwe bedoeling toe te passen.

Snelheidslimieten en fouten

Maken is beperkt tot 60 per uur per account en vervangen tot 30 per uur per account. Deze accountlimieten worden gedeeld door API- en MCP-aanroepers en zijn geen afzonderlijke quota per token. Bulkmoduswijzigingen hebben een extra limiet van 10 verzoeken per minuut. De normale API-limiet geldt ook voor deze routes; standaard is die 60 verzoeken per minuut per aanmeldingsgegeven. Een beperkt verzoek geeft 429 rate_limited terug; respecteer de Retry-After-header voordat je het opnieuw probeert.

Fouten gebruiken het standaardobject error met code, message, hint, request_id en retryable. Verwerk de machineleesbare code in plaats van tekst te vergelijken.

MCP-tools en controle op destructieve acties

MCP gebruikt dezelfde REST-autorisatie en antwoordvelden. De directe tools zijn:

De tools voor het maken van mailboxen create_mailbox_generated_password en bulk_create_mailboxes accepteren dezelfde optionele invoer create_app_password als REST.

Schrijftools accepteren ook een optionele idempotency_key. REST gebruikt het bodyveld mode voor mailboxmoduswijzigingen; de MCP-tool noemt deze invoer client_auth_mode. De bulkselectiecriteria hebben dezelfde toegangsregels en limiet van 1000 mailboxen als REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

In de zelfgehoste server vereist elke bovenstaande schrijfactie TREKMAIL_ALLOW_DESTRUCTIVE=true. Ook het maken van inloggegevens valt onder deze controle, omdat het mailboxtoegang geeft. Lijsten en accountgegevens lezen vereisen deze vlag niet. Vraag de gebruiker om de bedoelde wijziging aan inloggegevens of toegang goed te keuren voordat je een schrijfactie uitvoert. Directe tools die geheimen teruggeven, instrueren de agent om het wachtwoord één keer te tonen, de gebruiker het in de app te laten plakken en het nooit in bestanden of geheugen op te slaan of in latere berichten of toolaanroepen te herhalen.

Directoryprofielen van ChatGPT/OpenAI en Claude

Deze profielen geven bij maken en vervangen een beveiligde dashboardlink voor het instellen, in plaats van een geheim in de chat aan te maken. Ook het maken van een mailbox is daar een dashboardlink, dus het eerste app-wachtwoord komt van de kaart Mailbox aangemaakt in het dashboard, niet van create_app_password. De bestemming is /app/mailboxes/{mailbox_id}/security#app-passwords; de gebruiker meldt zich aan en voltooit de actie daar.

Het OpenAI-profiel biedt get_mailbox_app_password_setup_link en get_mailbox_app_password_replacement_setup_link. Het Claude-profiel houdt de namen create_mailbox_app_password en rotate_mailbox_app_password, maar geeft de beveiligde instellink terug in plaats van data.password. Beloof geen geheim uit die directorytools en vraag de gebruiker niet om er een in de conversatie te plakken.

Gebruik get_mail_client_setup voor verbindingsgegevens. Zie AI-agents verbinden voor algemene connectorconfiguratie. White Label-mailboxen gebruiken dezelfde API-functie en webmail- en mailhosts met het eigen merk; noem het aanmeldingsgegeven een app-wachtwoord in instructies voor gebruikers.