Mailkoppelingen via de API¶

Het concept achter tools staat in Tools.

Een mailkoppeling geeft het model toegang tot één mailbox: zoeken, lezen, markeren, verplaatsen, een concept opslaan en, als je dat toestaat, versturen. Core leest de mailbox over IMAP en verstuurt over SMTP, via de mailservers van je organisatie en met haar eigen login. Een koppeling opent de mailbox van je organisatie, zoals support@, of per aanroep de eigen mailbox van de persoon voor wie de beurt is. Een koppeling kan ook nieuwe mail opmerken en daarmee een workflow starten.

Een mailkoppeling stel je in via de API, zoals hieronder, of in de console onder Tools > Mailkoppelingen. Daar voeg je er een toe op een eigen pagina, zie je de servers, mappen en verzendgrenzen van een koppeling en of het volgen van nieuwe mail werkt, bewerk je hem tot een nieuwe versie, verwijder je hem, en laat je Core met Testen inloggen op de IMAP-server, en ook op de SMTP-server als de koppeling verstuurt. Bij een mailbox per persoon zie je op de pagina van de koppeling of je je eigen mailbox hebt verbonden, met Verbind je account en Verbinding verbreken; Testen meldt bij zo'n mailbox dat inloggen is geweigerd, omdat er bij een test geen persoon is om als in te loggen. Geheimen zie je nooit terug. Je sleutel heeft de capability tooling nodig, en de hosts van de IMAP- en SMTP-server moeten bij de toegestane hosts van je organisatie staan.

Een mailbox van de organisatie koppelen¶

curl -s -X POST "$CORE_URL/mail_connectors" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "support",
         "description": "De supportmailbox van Acme. Klanten mailen hier hun vragen.",
         "imap": {"host": "imap.acme.example", "port": 993, "security": "implicit_tls"},
         "smtp": {"host": "smtp.acme.example", "port": 587, "security": "starttls"},
         "folders": ["INBOX", "Afgehandeld"],
         "drafts_folder": "Drafts",
         "from_address": "support@acme.example",
         "send_allowed_domains": ["acme.example", "klant.example"],
         "auth": {"type": "basic", "username": "support@acme.example", "password": "..."}}'

Het antwoord is 201 met de koppeling, versie 1. tools op het antwoord noemt de tools die deze versie aanbiedt.

security is implicit_tls (IMAP 993, SMTP 465) of starttls (IMAP 143, SMTP 587). Een verbinding zonder versleuteling bestaat niet, en het certificaat moet altijd de naam van de host dragen.

GET /mail_connectors toont de koppelingen van je organisatie, GET /mail_connectors/{id} er één, PATCH wijzigt er een en DELETE verwijdert er een, met elk bericht dat nog niet verstuurd is en de toestemming van elke persoon. Verwijderen geeft 409 met de namen van de agents zolang de nieuwste versie van een agent een van de tools noemt.

Inloggen¶

auth is een van drie soorten. Het geheim wordt versleuteld opgeslagen en nooit teruggegeven.

mailbox is verplicht bij oauth_client_credentials en wordt bij de andere twee geweigerd. Het token-endpoint moet net als de servers bij je toegestane hosts staan.

De mailbox van een persoon¶

Met oauth_authorization_code heeft elke persoon een eigen mailbox achter dezelfde tools. Een aanroep logt in als de persoon voor wie de beurt is, dus twee mensen die dezelfde tool gebruiken, lezen twee verschillende mailboxen en zien elkaars mail nooit.

1. Registreer de koppeling met de gegevens van je provider. Vraag naast de scope voor IMAP ook openid en email: Core leest het adres van de mailbox uit het ID-token dat de provider bij het inloggen teruggeeft.

   curl -s -X POST "$CORE_URL/mail_connectors" \
       -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
       -d '{"name": "inbox",
            "description": "De eigen mailbox van de persoon voor wie je werkt.",
            "imap": {"host": "imap.provider.example", "port": 993, "security": "implicit_tls"},
            "auth": {"type": "oauth_authorization_code",
                     "authorize_url": "https://id.provider.example/authorize",
                     "token_url": "https://id.provider.example/token",
                     "client_id": "artific-core",
                     "scopes": ["openid", "email", "<de IMAP-scope van je provider>"]}}'
   

2. Registreer <de publieke basis-URL van Core>/api/v1/oauth/callback als redirect-URI bij je provider.

3. Noem de persoon met user op elk verzoek, en vraag de persoon in te loggen. Dat werkt precies als bij een API-koppeling (De persoon logt zelf in), met dezelfde routes onder /mail_connectors/{id}/authorizations:

   curl -s -X POST "$CORE_URL/mail_connectors/mail_01J.../authorizations" \
       -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
       -d '{"user": "u_9f31", "return_url": "https://jouw-app.example/instellingen"}'
   

   Geef de url uit het antwoord aan de persoon. GET .../authorizations/{user} zegt of Core haar toestemming heeft, en DELETE .../authorizations/{user} vergeet die.

Bij het inloggen bewaart Core het adres dat de provider in het ID-token noemt, versleuteld bij de toestemming. Zegt de provider dat het adres niet geverifieerd is, dan wordt er geen mailbox gekoppeld en leest de persoon Your sign-in did not confirm a verified email address, so no mailbox was connected., of komt ze terug op je return_url met authorization=denied. De mailserver controleert het adres tegen het token, dus een persoon opent nooit een mailbox die ze zelf niet al kon openen.

Zo'n mailbox heeft geen persoon achter werk dat buiten een beurt draait. Daarom wordt hij nooit voor zichzelf bewaakt en verstuurt hij nooit voor een persoon; een concept opslaan kan wel. De enige uitzondering is de eigen mailbox van een serviceaccount. Als het beheer de koppeling als mailbox van het account noemt, bewaakt mail_watch hem op nieuwe mail met de watch van de versie, elk nieuw bericht een mail.received-gebeurtenis van het account met service_account; met mail_send versturen de beurten van het account via die koppeling onder de verzendregels van de versie, en leest elke andere beurt This mailbox sends only for its service account. De authorizations-routes geven 409 bij een koppeling van een andere soort.

De tools¶

Welke tools een versie aanbiedt, volgt uit wat ze instelt. Elke map die een tool mag noemen, is een keuze uit folders.

Zoeken en lezen markeren nooit iets als gelezen. Een concept en een bericht nemen to, cc, subject en body, en met reply_to_uid een antwoord op een bericht, met de headers die een antwoord bij dat bericht houden.

Bied de tools aan op naam, {"type": "tool", "name": "mail__support__search"}, of allemaal tegelijk met een toolset met het patroon mail__support__*.

Versturen¶

Alles wat een bericht kan tegenhouden, beslist Core terwijl het model wacht: elke ontvanger is één adres in precies een van de send_allowed_domains, er zijn er hoogstens max_recipients, de SMTP-host is toegestaan, en het bericht krijgt een van de sends_per_hour plaatsen van dit klokuur.

Daarna leest het model The mail is queued and will be sent. Het bericht wordt verstuurd nadat de beurt is afgerond; een beurt die daarna mislukt, verstuurt niets. Een plaats in het uur die zo'n beurt al nam, blijft wel gebruikt. Core probeert opnieuw zolang de server onbereikbaar is of een tijdelijke fout geeft; elke poging draagt dezelfde Message-ID, zodat een herhaling als hetzelfde bericht te herkennen is. Weigert de server het bericht definitief, dan probeert Core het niet opnieuw.

Hoe het afliep, staat in het auditspoor: mail_connector.mail_sent, mail_connector.mail_refused of mail_connector.mail_dropped, met id's en zonder adressen of tekst. Hoe het ook afloopt, daarna bewaart Core de tekst van het bericht niet langer.

Nieuwe mail¶

Stel watch in om nieuwe mail in één map op te merken:

curl -s -X PATCH "$CORE_URL/mail_connectors/mail_01J..." \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"watch": {"folder": "INBOX", "poll_seconds": 300}}'

Elk nieuw bericht in die map wordt één gebeurtenis mail.received, met het id van de koppeling in mail_connector, de folder en de uid, en nooit een adres, een onderwerp of een tekst. Mail die al in de map stond toen het bewaken begon, telt niet als nieuw. Eén keer kijken meldt hoogstens 100 nieuwe berichten, oudste eerst; de rest volgt de volgende keer. Hoe je daarmee een workflow start, staat in Nieuwe mail.

Een read van de koppeling toont hoe het bewaken gaat:

watch_polled_at zegt wanneer Core het laatst keek. Na een mislukking wacht Core steeds langer, tot een uur, voor het opnieuw probeert. {"watch": null} stopt het bewaken. Een andere map kiezen begint opnieuw: Core telt dan pas mail die daarna binnenkomt.

Een koppeling testen¶

POST /mail_connectors/{id}/test logt in bij de IMAP-server en opent de eerste map alleen om te lezen, en logt bij een koppeling die verstuurt ook in bij de SMTP-server. Er wordt niets opgeslagen en niets verstuurd.

{"imap": {"ok": true, "code": "ok"}, "smtp": {"ok": false, "code": "auth_failed"}}

code is ok, denied (de host of zijn adres is niet toegestaan), unreachable, auth_failed of refused; smtp is null bij een koppeling die niet verstuurt. Een mailbox van een persoon heeft bij de test geen persoon, en antwoordt daarom auth_failed voor IMAP.

Versies¶

Een koppeling is geversioneerd. Een PATCH die wijzigt wat de koppeling doet, maakt een nieuwe versie; een PATCH van alleen auth, mailbox of region maakt er geen. Met een expliciete null zet je een tool uit: smtp, from_address of "send_allowed_domains": [] stopt het versturen, en drafts_folder of from_address het concept.

GET /mail_connectors/{id}/versions toont de versies, nieuwste eerst (?order=asc voor oudste eerst), en GET /mail_connectors/{id}/versions/{version} er één. Pin een versie zoals bij elke koppeling: {"type": "tool", "name": "mail__support__read", "version": 2} (Een versie vastpinnen).

Een mailkoppeling gaat niet mee in een publicatie: elke organisatie koppelt haar eigen mailbox.

Wat het model leest als iets mislukt¶

Het model leest een vaste zin, nooit de woorden van de server, die een adres of een onderwerp kunnen noemen. De beurt gaat door.

Bij een persoon zonder toestemming leest het model de zin met een inlog-URL uit Vraag de persoon in te loggen, en bij een verzoek dat geen user noemt de zin This tool needs a person's login, and the request named no user.

Bij het registreren of wijzigen:

Elke route heeft een tweeling onder /tenants/{tenant_id}/mail_connectors voor een beheerder die met een beheerderstoken werkt, met dezelfde velden en antwoorden.