@marlinjai/mail-sdk 0.5.0 → 0.6.1

package/README.md

@@ -81,6 +81,122 @@ package has not wrapped yet, or to pass a raw `AbortSignal`.
 const workspace = await mail.request('workspace.get');
 ```
 
+## Recipe: a confirmation letter after a form
+
+The pattern for any one-to-one mail your backend sends in answer to something a
+person did (a contact form, a signup for updates, a booking request): a
+**letter**, which is a mailing with no topic and one recipient
+(`docs/public/mail-contract.md`, "Letters"). It takes three calls, each with an
+idempotency key derived from **your own** key for the submission, so a retried
+request sends one letter, never two.
+
+```ts
+import { createMailClient, MailApiError } from '@marlinjai/mail-sdk';
+
+const mail = createMailClient({ baseUrl: process.env.MAIL_SERVICE_URL!, apiKey: process.env.MAIL_SERVICE_API_KEY! });
+
+/**
+ * submissionKey: a stable id you already store for the form submission.
+ * locale: the language the person used on your site ('fr', 'de', ...).
+ * reason: the key the form's drop-down sent ('venue', 'press', ...), never a sentence.
+ */
+export async function sendConfirmation(submissionKey: string, email: string, name: string, locale: string, reason: string) {
+  const mailing = await mail.mailings.create(
+    {
+      template_id: process.env.MAIL_TEMPLATE_CONTACT_CONFIRMATION!,
+      provider_id: process.env.MAIL_PROVIDER_ID!,
+      // No `topic`: that is what makes it a letter.
+      send_locale: locale,
+      metadata: { kind: 'contact_confirmation', submission: submissionKey },
+    },
+    { idempotencyKey: `${submissionKey}:create` },
+  );
+  await mail.mailings.addRecipients(
+    mailing.id,
+    { recipients: [{ email, merge: { first_name: name, reason } }] },
+    { idempotencyKey: `${submissionKey}:recipients` },
+  );
+  await mail.mailings.send(mailing.id, { idempotencyKey: `${submissionKey}:send` });
+  return mailing.id;
+}
+```
+
+What each piece does, and why:
+
+- **No `contacts.upsert` first.** Adding a recipient by email creates the
+  contact when there is none (subscribed to nothing, since a letter has no
+  topic) and never changes one that exists. A form usually takes an address
+  without proof that the person owns it, so a submission should not be able to
+  rename someone, change their language or subscribe them to anything; leaving
+  the upsert out guarantees that. Per-letter values (the name as typed, a
+  gathering or product name) go in the recipient's `merge`, which fills the
+  template's `{{first_name}}` and other fields for this letter only.
+- **The language.** `send_locale` picks the template's **ready** version in that
+  language, and the template's main language when there is none; subject and
+  preheader come from the same version. Pass the language the person used on
+  your site, validated against the ones you support.
+- **Choices, not prose.** When the letter's wording depends on what the person
+  did (which reason they picked, whether they filled an optional field, whether
+  a name is known), the template holds the sentences as **insertions**, in every
+  language, and you send only the value that chooses: `reason: 'venue'`,
+  `about: true`, the name (`docs/public/mail-contract.md`, "Insertions"). Never
+  compute a sentence in your code and pass it as a merge value: it would be in
+  one language, unreviewed, inside a letter in another. Offer the choices as a
+  fixed list (a drop-down, never free text) built from the template's keys,
+  and check your data against them before sending:
+
+  ```ts
+  import { insertionInputs } from '@marlinjai/mail-sdk';
+
+  const template = await mail.templates.get(process.env.MAIL_TEMPLATE_CONTACT_CONFIRMATION!);
+  const accepted = insertionInputs(template.insertions).reason?.keys ?? [];
+  // ['venue', 'expert', 'partnership', 'press']: anything else gets the "otherwise" text.
+  ```
+
+  A value no choice takes still sends (with the `otherwise` text) and is
+  recorded as a miss (`matched: false` in `insertions` on `message.sent`, and in
+  `mailings.languages`), so a drift between your form and the template shows up
+  instead of passing silently.
+- **The provider** (`provider_id`, required) is the sending account the
+  workspace has set up: find its id with `mail.providers.list()` or on the
+  dashboard's Providers page, and keep it in configuration next to the
+  template ids. A letter uses the same provider as any other mailing.
+- **Subject and preheader** come from the template. `mailings.create` refuses a
+  `subject` that differs from the template's (`subject_from_template`); pass one
+  only for a template that has none.
+- **Idempotency.** A replay with the same key and the same body within 24 hours
+  answers with the first response and changes nothing, so the create returns
+  the first mailing's id and the send does not send again. Derive the keys from
+  your submission key (not from a random value per attempt), keep the body of
+  each call identical across attempts, and retry within the 24 hours. The same
+  key with a different body is `idempotency_key_reused`: that is a bug in the
+  caller, not something to retry. Refusals are kept too: every answer below
+  500 (a `validation_failed`, an `unknown_provider`) is stored against its key
+  and replayed, so retrying the same key after fixing the cause gets the old
+  refusal back. When a retry changes the body (a provider id looked up again,
+  say), give that call a key of its own, for example
+  `${submissionKey}:create:${providerId}`: a refused call created nothing, so
+  a new key cannot duplicate a letter. Only a 5xx releases the key.
+- **Consent.** A letter reaches anyone not blocked on every topic (an
+  all-topics unsubscribe, a hard bounce, a complaint). A blocked person's
+  recipient ends `skipped` with `skip_reason: "suppressed"`. The letter still
+  needs `{{unsubscribe_url}}` in the template; it opens the hosted page with
+  every topic and "unsubscribe from everything" first.
+- **Knowing what happened.** `send` answers once the letter is queued, not
+  delivered. The `message.sent` and `message.failed` webhooks carry
+  `mailing_id` and your metadata as `mailing_metadata`, so the receiver can
+  file the outcome against the submission without a lookup (see [A webhook receiver](#a-webhook-receiver)).
+- **Bound it yourself.** Idempotency stops a retry, not someone submitting the
+  form again and again with fresh submissions to flood one inbox. Count the
+  letters you sent to an address recently and stop at a small number.
+- **Never let the letter fail the form.** Send it after the submission is
+  safely stored, catch `MailApiError` and network errors, record them, and tell
+  the person their submission worked.
+
+Testing against a fake: implement the same replay rule (same key and body,
+same answer), `addRecipients` idempotent on the address, and at most one
+recipient on a letter, or the tests prove less than the real service does.
+
 ## The dashboard variant: server-only, per signed-in person
 
 The mail service's own dashboard (`apps/dashboard`) signs people in through