SDK

Een e-mail versturen

`emails.send`: één bericht, nu of later.

emails.send

send-email.ts

const email = await openemail.emails.send({  from: { email: '[email protected]', name: 'Acme Billing' },  to: ['[email protected]', 'Grace <[email protected]>'],  cc: '[email protected]',  bcc: [{ email: '[email protected]' }],  replyTo: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached.</p>',  text: 'Invoice attached.',  headers: { 'X-Campaign': 'invoices' },  attachments: [{ filename: 'invoice.pdf', content: pdfBytes }],  threadId: 'thread_…',  scheduledAt: 'PT1H',  tags: { order: '4021' },  tracking: { opens: true, clicks: true },})

to, cc en bcc accepteren één ontvanger of meerdere, en een enkele wordt voor je in een array gewikkeld. Elk mag een kaal adres zijn, Name <addr@host>, of { email, name }.

Parameters

fromRecipientInputverplicht: De afzender. Een kaal adres, `Name <addr@host>`, of een object. Moet er een zijn waarvandaan deze sleutel mag versturen. Er is geen terugvalafzender, omdat de terugval het standaardadres van de workspace zou zijn, en dat verandert naarmate adressen komen en gaan.
toRecipientInput | RecipientInput[]verplicht: Eén ontvanger of meerdere; een enkele wordt voor je in een array gewikkeld. Maximaal 50 over to, cc en bcc samen.
ccRecipientInput | RecipientInput[]: Telt mee voor de limiet van 50 ontvangers.
bccRecipientInput | RecipientInput[]: Wordt nooit genoemd in de bytes die iemand anders ontvangt, omdat er per ontvanger één envelop verzonden wordt.
replyToRecipientInput: Eén adres, verstuurd als de Reply-To-header.
subjectstring: Maximaal 998 tekens, de regellimiet uit RFC 5322. Standaard leeg.
htmlstring: Een van html, text, draftId of template is verplicht. HTML is wat ontvangers zien wanneer zowel html als text gegeven zijn.
textstring: Het platte-tekstdeel.
template{ id, version?, props?, slots? }: Render een opgeslagen sjabloon aan de serverkant. `version` pint vast; laat het weg om te gebruiken wat gepubliceerd is op het moment dat het verzoek geaccepteerd wordt. Een onbekende of ontbrekende prop is een 422 in plaats van een leegte in het bericht.
draftIdstring: Verstuur een opgeslagen concept onder deze envelop.
headersRecord<string, string>: `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority en Feedback-Id. Alles wat het transport zelf instelt wordt geweigerd in plaats van stilletjes weggelaten.
attachmentsAttachmentInput[]: `{ filename, content, contentType? }`, of `{ fileId }` die een bestand noemt dat al in de workspace staat. Geef bytes mee als content en ze worden voor je base64-gecodeerd. 20 bestanden, waarbij inline bestanden samen op 5 MB na decodering zijn afgetopt. Een opgeslagen bestand mag groter zijn en reist als downloadlink.
attachmentDeliveryAttachmentDeliveryMode: `mime`, `link` of `auto`. `auto` draagt bestanden als downloadlinks zodra ze 2 MB passeren op een domein met een actief bestandsdomein, en anders binnen het bericht. Weggelaten geldt de mailboxinstelling, en die staat standaard op `auto`.
threadIdstring: Antwoord binnen een bestaande thread. Het transport schrijft In-Reply-To en References.
scheduledAtDate | string: Een Date, een ISO-8601-tijdstip, of een duur zoals `PT1H`. Tot een jaar vooruit, nooit in het verleden. Niet te combineren met cancellableForSeconds.
cancellableForSecondsnumber: 0 tot 900. Een ongedaan-maken-venster op een directe verzending: het undo-mechanisme van de composer, blootgesteld in plaats van vastgezet.
tagsRecord<string, string>: Maximaal 10 labels, worden teruggegeven en zijn filterbaar. Nooit geïnterpreteerd.
signatureboolean: Of dit bericht de handtekening draagt van het adres waarvandaan het verstuurd wordt, en dat is de eigen handtekening van dat adres of anders die welke voor Alle adressen is ingesteld. Standaard true, omdat een handtekening bij het adres hoort en niet bij de client die het bericht verstuurde. Zet hem op `false` voor de mail die een programma namens iemand verstuurt, zoals een bon, een wachtwoordherstel of een samenvatting, waar geen van alle de ondertekening van een persoon onder wil.
tracking{ opens?, clicks? }: Of er voor dit bericht een open-pixel wordt toegevoegd en links worden herschreven. Aan, tenzij de eigenaar van de workspace tracking heeft uitgezet voor het adres waarvandaan het verstuurd wordt of voor Alle adressen, en elk veld dat hier wordt opgegeven beslist dat ene bericht, welke kant het adres ook op staat.
translate{ to, from?, subject?, includeOriginal? }: Verstuur het in de taal van de ontvanger. `to` accepteert een code, een Engelse naam of de eigen naam van de taal; `subject` en `includeOriginal` staan beide standaard op true. Opgelost wanneer het verzoek geaccepteerd wordt, zodat een gepland bericht de goedgekeurde woorden draagt. Geweigerd naast `draftId`.

Antwoord

idstring: De verzend-id, `msg_…`. Gebruik die voor `get`, `cancel`, `reschedule` en `getTracking`.
statusEmailStatus: queued, scheduled, sending, sent, partial, cancelled of failed. Lees dit in plaats van het feit dat de promise oploste. `partial` is een eigen status: sommige ontvangers hebben het en dat kan niet ongedaan gemaakt worden, dus opnieuw proberen is verkeerd en mislukking melden is een leugen.
mode'live' | 'test': Welk soort sleutel het verstuurde. Een testverzending wordt vastgelegd en nooit uitgezonden.
fromstring: Het adres dat daadwerkelijk geautoriseerd en op de lijn gezet werd, wat niet altijd het gevraagde is.
subjectstring | null: Zoals verstuurd.
messageIdstring | null: De Message-ID uit RFC 5322. Null tot de MIME bestaat. De verzenddienst herschrijft de header onderweg naar buiten, dus geen enkele bounce of bezorgingsrapport draagt deze waarde. `id` is waarop een gebeurtenis terugkomt.
threadIdstring | null: De thread waarin het landde.
transportstring | null: Hoe het bericht vertrok. Null tot de verzending.
attemptsnumber: Hoe vaak de verzending geprobeerd is.
lastErrorstring | null: Waarom de laatste poging faalde, letterlijk.
scheduledAtstring | null: ISO-tijdstip waarop het moet vertrekken.
cancellableUntilstring | null: Zolang nu vóór dit moment ligt, werkt annuleren nog.
sentAtstring | null: ISO-tijdstip waarop het vertrok.
tagsRecord<string, string>: Wat je stuurde, teruggegeven.
sourceEmailSource: composer, api, mcp, ai of queue: welke oppervlakte erom vroeg. `api` is deze client.
createdAtstring: ISO-tijdstip waarop het record is geschreven.
replayedboolean: Waar wanneer een Idempotency-Key overeenkwam met een verzending die al bestond. Er is niets nieuws verstuurd, en dit is het oorspronkelijke bericht.
translationEmailTranslationResource | undefined: Alleen aanwezig op een bericht dat vertaald is, en alleen waar het hele opgeslagen verzoek wordt meegedragen: dit antwoord en `get`. `{ language, languageName, detectedSourceLanguage, subject, includeOriginal }`, allemaal codes en geen taalrijen. Een lijstrij heeft het nooit, dus de afwezigheid daar zegt niets, de ene kant noch de andere.

In de taal van de ontvanger

translate schrijft het bericht in de taal van iemand anders voordat het weggaat. De body, en het onderwerp tenzij je dat uitzet, wordt vertaald wanneer de API het verzoek accepteert, en wat eruit kwam is wat uitgaat: een vertaling die niet geproduceerd kon worden weigert de verzending in plaats van hem te posten in de taal waarin je hem schreef.

translate.ts

const email = await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  translate: { to: 'de' },}) console.log(email.translation)// { language: 'de', languageName: 'German', detectedSourceLanguage: 'en', subject: true, includeOriginal: true }

Niemand heeft dat gelezen voordat het wegging. emails.translate is dezelfde rondgang, één stap eerder gestopt. Laat het aan een persoon zien, laat die het wijzigen, en verstuur dan wat ze goedkeurden zonder enige translate op de aanroep. Die opnieuw meegeven zou een tweede keer vertalen en hun wijzigingen weggooien.

preview-translation.ts

const preview = await openemail.emails.translate({  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  to: 'de',}) console.log(preview.language.native, preview.detectedSourceLanguage) const approved = await showToSomebody(preview) await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: approved.subject,  html: approved.html,})

render-picker.ts

import { LANGUAGES, isRtlLanguage, languageByCode, openemail, resolveLanguage } from '@openemail/sdk' LANGUAGES.length // 200 const current = await openemail.languages.list() resolveLanguage('Deutsch')?.code // 'de'resolveLanguage('zh-TW')?.code // 'zh-Hant'languageByCode('DE')?.native // 'Deutsch'isRtlLanguage('ar') // true

De tabel wordt meegeleverd, in kiezervolgorde, zodat een kiezer gevuld kan worden vóór het eerste verzoek. languages.list() levert dezelfde rijen van de lijn op als een gewone array, voor een aanroeper die liever de huidige heeft dan die waarmee deze versie is uitgebracht. resolveLanguage accepteert een code, een Engelse naam, een endoniem of een alias (zh-TW is een alias van een code die niet meer vermeld staat), languageByCode matcht een exacte code zonder op hoofdletters te letten, en zestien van de rijen lopen van rechts naar links. Doorzoek native, label en code samen, toon native als eerste, en sla de code op.

emails.translate wordt niet automatisch herhaald. Het kost modelaanroepen en schrijft niets, dus er is niets om idempotent te maken en een herhaling na een onbeantwoord verzoek zou alleen hetzelfde antwoord twee keer kopen.

Een taal die nergens toe oplost is een validation_error op translate.to, voordat er iets verstuurd is.
translation_too_long boven 30.000 tekens, translation_not_configured wanneer de installatie geen AI geconfigureerd heeft, translation_failed wanneer de provider niet antwoordde. Geen van alle verstuurt het bericht als terugval onvertaald.
Werkt samen met template: de GERENDERDE uitvoer is wat vertaald wordt, dus één opgeslagen body bedient elke taal waarin je klanten lezen. Een sjabloon dat een heel document rendert behoudt zijn doctype, zijn <style>-blokken en zijn @font-face-regels: alleen de body gaat naar het model en de rest wordt er weer omheen gezet. De <title> blijft ongemoeid, en die wordt sowieso nergens getoond.
Een herhaling kost niets extra. De vertaling maakt geen deel uit van de idempotentie-vingerafdruk (het verzoek wel, translate inbegrepen), dus een onbeantwoorde verzending herhalen met dezelfde Idempotency-Key speelt het bericht dat al bestaat opnieuw af in plaats van een tweede te vertalen en te versturen.
Een vertaald bericht dat in de wachtrij staat of gepland is, ligt vast wat de bewoording betreft. emails.reschedule verschuift het nog steeds; veranderen wat het zegt betekent annuleren en opnieuw versturen.

Bijlagen

content is base64 op de lijn. Geef bytes mee en ze worden voor je gecodeerd.

attachment.ts

attachments: [  { filename: 'invoice.pdf', content: pdfBytes, contentType: 'application/pdf' },]

toBase64 wordt geëxporteerd mocht je het elders nodig hebben. Het werkt in stukken, wat btoa(String.fromCharCode(...bytes)) niet doet. Dat laatste faalt op alles boven ongeveer 100 kB, en het faalt op het echte bestand en niet op het bestand waarmee je testte.