Mailconcepten klaarzetten via de API

Je eigen app weet vaak precies welke mail er nodig is: een offerte bevestigen, een klant antwoorden over een bestelling. Met deze API zet je app die mail als concept klaar in 1plek, namens een collega en vanaf een inbox van het bedrijf. Je collega vindt het concept in Concepten (of in het gesprek, bij een antwoord), leest het na en verstuurt het zelf.

Een sleutel maken

Ga naar Bedrijfsinstellingen → Koppelingen → Je app, blok Mailconcepten klaarzetten, en maak een sleutel. Die heeft het recht mail:draft, hoort bij één bedrijf en wordt gehasht opgeslagen — je ziet 'm één keer. Op dezelfde plek trek je een sleutel weer in; daarna geeft elke aanroep 401.

Wat je app wel en niet kan

De sleutel geeft je app geen eigen toegang tot de inbox. Je app zet iets klaar namens een collega, en alleen als die collega dat in 1plek zelf ook had gekund:

• de collega (actorEmail) heeft een account in 1plek, mag inloggen en werkt nu bij dit bedrijf;
• de inbox (from) is een inbox van dit bedrijf, en de collega mag die inbox gebruiken;
• bij een antwoord: de collega mag het gesprek zien.

actorEmail is het hoofdadres van het account in 1plek. Een extra inlogadres (een gekoppeld privé-account) telt hier niet: dat opent alleen de persoonlijke plek.

Elk concept laat zien waar het vandaan komt: in Concepten en bij het openen staat "Klaargezet via <naam van de sleutel> namens <collega>". Geef je sleutel dus een herkenbare naam.

Een concept klaarzetten

curl -X POST \
  https://iam.1plek.com/api/platform/companies/jouw-bedrijf/mail/drafts \
  -H "Authorization: Bearer $ONEPLEK_API_KEY" \
  -H "Idempotency-Key: 6f1c2a1e-4b7d-4c1e-9d55-2f9a0c3e7b10" \
  -H "Content-Type: application/json" \
  -d '{
    "actorEmail": "collega@jouwbedrijf.nl",
    "from": "info@jouwbedrijf.nl",
    "to": [{ "email": "klant@example.com", "name": "Sam de Klant" }],
    "cc": [],
    "subject": "Je offerte",
    "html": "<p>Hoi Sam,</p><p>Hierbij je offerte.</p>",
    "inReplyTo": "<abc123@mail.example.com>",
    "context": { "offerte": "Q-2041" }
  }'

jouw-bedrijf is de korte naam van het bedrijf in 1plek (zie Je app). Het adres van je 1plek-werkruimte kan afwijken van iam.1plek.com; gebruik het adres dat bij je sleutel staat.

Headers

Velden

Namen bij ontvangers worden nu niet gebruikt; 1plek toont de naam uit de contacten.

Antwoord of nieuwe mail

Met inReplyTo zoekt 1plek de mail met die Message-ID in de inbox van from. Staat die in een gesprek dat je collega mag zien, dan wordt het concept een antwoord in dat gesprek. Anders, of zonder inReplyTo, wordt het een nieuwe mail in Concepten.

Een collega heeft per gesprek één antwoord-concept. Staat daar al een concept van die collega, dan blijft dat onaangeroerd (het kan half getypte tekst zijn) en wordt jouw concept een nieuwe mail in Concepten.

Antwoord bij succes: 201

{
  "draftId": 123,
  "conversationId": null,
  "openUrl": "/inbox/compose?draft=123"
}

Dezelfde aanroep nog eens

Met dezelfde Idempotency-Key bij hetzelfde bedrijf binnen 24 uur krijg je hetzelfde antwoord terug (201, zelfde draftId) en er komt geen tweede concept bij. Zo kun je na een time-out veilig opnieuw proberen. Dat geldt ook als het concept intussen is aangepast, verstuurd of weggegooid.

Gebruik je dezelfde sleutel binnen 24 uur met andere inhoud, dan krijg je 422. Na 24 uur is de sleutel vergeten en maakt dezelfde waarde een nieuw concept.

Foutmeldingen

Een fout heeft altijd de vorm { "error": "<zin>" }. Deze zinnen zijn vast; je kunt ze aan je gebruiker tonen.

De 403 voor het bedrijf zegt bewust niet of het adres een account heeft: je app hoort alleen te weten dat het voor dit bedrijf niet kan.

Grenzen

• Per sleutel maximaal 60 concepten per uur, per bedrijf (alle sleutels samen) 200.
• Staat het onderdeel Inbox van het bedrijf uit in 1plek, dan weigert de API met 409. Er wordt niets bewaard.
• Een nieuwe mail staat in Concepten bij de collega's van dit bedrijf; een antwoord-concept is persoonlijk en staat alleen bij de collega namens wie het klaargezet is.