sently 1.0.1 → 1.2.0

package/site/content/docs/transports/mailpit.mdx

@@ -8,8 +8,13 @@ source: "src/transports/mailpit.ts"
 Catch outbound email in a local [Mailpit](https://github.com/axllent/mailpit) instance while you develop.
 Use it for the welcome email or password-reset flow before you point at a production provider.
 
+<LiveVerified>
+Email send against a local Mailpit instance succeeded in sently’s integration suite (SMTP capture + REST list/get).
+</LiveVerified>
+
 <Callout title="The one rule">
   Use Mailpit only in development — swap to a production transport before you deploy.
+  Vendor extras stay on the `MailpitTransport` instance — never on `createMailer`.
 </Callout>
 
 ## Quick start
@@ -72,27 +77,117 @@ console.log(inbox.messages[0]?.Subject);
 | `apiAuth` | `{ user, pass }` | — | Basic auth for the UI/API |
 
 `provider` is `"mailpit"`. `verify()` checks SMTP; `close()` closes the socket adapter.
+`webUrl` is the UI base (same as `apiUrl`).
+
+## Features
 
-## REST helpers
+Pick a branch. Channel send goes through `mailer`; everything else is called on `mailpit`.
+Message ids may be a Mailpit id or `"latest"`.
 
-Vendor extras stay on the transport instance (not on `createMailer`):
+<Tabs items={["Send", "List", "Search", "Message", "Headers", "HTML check", "Link check", "Read", "Delete"]}>
+  <Tab value="Send">
 
-| Method | Mailpit API | Meaning |
-| --- | --- | --- |
-| `messages({ limit?, start? })` | `GET /api/v1/messages` | List captured messages (newest first) |
-| `getMessage(id)` | `GET /api/v1/message/{id}` | Full message body |
-| `deleteMessages(ids)` | `DELETE /api/v1/messages` | Delete by id |
-| `deleteAll()` | `DELETE` with empty `IDs` | Clear the inbox |
-| `webUrl` | — | UI base URL (same as `apiUrl`) |
+Transactional send via the channel mailer (SMTP into Mailpit).
 
 ```ts
+await mailer.send({
+  from: "dev@example.com",
+  to: "you@example.com",
+  subject: "Welcome",
+  html: "<h1>Hello</h1><a href=\"https://example.com\">Go</a>",
+  text: "Hello",
+});
+```
+
+  </Tab>
+  <Tab value="List">
+
+List captured messages (`GET /api/v1/messages`), newest first.
+
+```ts
+const inbox = await mailpit.messages({ limit: 10, start: 0 });
+console.log(inbox.total, inbox.messages[0]?.Subject);
+```
+
+  </Tab>
+  <Tab value="Search">
+
+Find a message with Mailpit’s query syntax (`subject:`, `to:`, `tag:`, …).
+
+```ts
+const found = await mailpit.search("subject:Welcome", { limit: 1 });
+console.log(found.messages[0]?.ID);
+```
+
+  </Tab>
+  <Tab value="Message">
+
+Full body for the message id (or `"latest"`).
+
+```ts
+const full = await mailpit.getMessage("latest");
+console.log(full.Text, full.HTML);
+```
+
+  </Tab>
+  <Tab value="Headers">
+
+Header map for assertions (`Message-Id`, custom headers, …).
+
+```ts
+const headers = await mailpit.getHeaders("latest");
+console.log(headers.Subject, headers["Message-Id"]);
+```
+
+  </Tab>
+  <Tab value="HTML check">
+
+Client HTML/CSS compatibility score from Mailpit’s checker.
+
+```ts
+const html = await mailpit.htmlCheck("latest");
+console.log(html.Total.Supported, html.Total.Unsupported, html.Warnings.length);
+```
+
+Needs an HTML part — plain-text-only messages can return `400`.
+
+  </Tab>
+  <Tab value="Link check">
+
+Probe links and images in the message (`follow` optional).
+
+```ts
+const links = await mailpit.linkCheck("latest", { follow: true });
+console.log(links.Errors, links.Links);
+```
+
+  </Tab>
+  <Tab value="Read">
+
+Mark messages read or unread between assertions.
+
+```ts
+const inbox = await mailpit.messages({ limit: 1 });
+await mailpit.setRead([inbox.messages[0]!.ID], true);
+// empty ids → update every message
+await mailpit.setRead([], false);
+```
+
+  </Tab>
+  <Tab value="Delete">
+
+Delete by id, or clear the whole inbox.
+
+```ts
+await mailpit.deleteMessages(["abc"]);
 await mailpit.deleteAll();
-await mailer.send({ from: "a@test.com", to: "b@test.com", subject: "T", text: "ok" });
-const list = await mailpit.messages({ limit: 1 });
-const full = await mailpit.getMessage(list.messages[0]!.ID);
 ```
 
-REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage("")` throws with status `400`.
+  </Tab>
+</Tabs>
+
+REST failures throw `MailpitError` (`provider: "mailpit"`).
+Empty `getMessage("")` / `search("")` throws with status `400`.
 
 ## Troubleshooting
 
@@ -103,6 +198,9 @@ REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage(""
   <Accordion title="API helpers fail but send works">
     SMTP and the UI/API can bind to different hosts. Set `apiUrl` (and `apiAuth` if the UI requires Basic auth).
   </Accordion>
+  <Accordion title="htmlCheck returns 400">
+    The message has no HTML part, or Mailpit could not parse it. Send `html` (not only `text`) and retry with `"latest"` or the message id.
+  </Accordion>
   <Accordion title="Should I use createSMTPMailer instead?">
     Yes, if you only need SMTP. `MailpitTransport` adds local defaults and REST helpers for tests and inspection.
   </Accordion>
@@ -110,14 +208,16 @@ REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage(""
 
 ## Learn more
 
+- [Inbucket](./inbucket) — another local SMTP catcher with a mailbox REST API
 - [SMTP](./smtp) — generic SMTP when you are not on Mailpit
 - [Preview](/docs/decorators/preview) — write `.eml` files to disk instead
 - [Email channel](/docs/channels/email) — `createMailer` contract
+- [Mailpit API](https://mailpit.axllent.org/docs/api-v1/) — full REST surface on the catcher
 
 ## Next
 
 <Cards>
+  <Card title="Inbucket" href="/docs/transports/inbucket" />
   <Card title="Email channel" href="/docs/channels/email" />
-  <Card title="SMTP" href="/docs/transports/smtp" />
   <Card title="Transports" href="/docs/transports" />
 </Cards>

package/site/content/docs/transports/meta.json

@@ -3,6 +3,8 @@
   "icon": "Truck",
   "pages": [
     "index",
+    "---Multi-channel---",
+    "taqnyat",
     "---Email---",
     "smtp",
     "resend",
@@ -15,19 +17,19 @@
     "plunk",
     "sparkpost",
     "mailtrap",
-    "mailpit",
     "loops",
     "cloudflare-email",
     "sndr",
-    "taqnyat-mail",
+    "hostinger",
+    "---Email Dev---",
+    "mailpit",
+    "inbucket",
     "---SMS---",
     "twilio-sms",
-    "taqnyat-sms",
     "msegat",
     "unifonic",
     "---WhatsApp---",
     "whatsapp-cloud",
-    "taqnyat-whatsapp",
     "---Push---",
     "webpush",
     "fcm"

package/site/content/docs/transports/smtp.mdx

@@ -55,7 +55,7 @@ await mailer.send({
 | `pool` | `boolean` | `false` |
 | `dkim` | `DKIMConfig` | optional |
 
-For local capture with defaults and REST helpers, use [Mailpit](./mailpit) instead of hand-wiring `localhost:1025`.
+For local capture with defaults and REST helpers, use [Mailpit](./mailpit) or [Inbucket](./inbucket) instead of hand-wiring SMTP ports.
 
 ## Troubleshooting
 
@@ -67,13 +67,14 @@ For local capture with defaults and REST helpers, use [Mailpit](./mailpit) inste
     Pass an explicit transport, or use `createSMTPMailer` for relay configuration.
   </Accordion>
   <Accordion title="Local development without a real relay">
-    Use [Mailpit](./mailpit) (`sently/transports/mailpit`) or [Preview](/docs/decorators/preview).
+    Use [Mailpit](./mailpit), [Inbucket](./inbucket), or [Preview](/docs/decorators/preview).
   </Accordion>
 </Accordions>
 
 ## Learn more
 
 - [Mailpit](./mailpit) — local SMTP catcher with inbox API
+- [Inbucket](./inbucket) — local SMTP catcher with mailbox REST API
 - [Email channel](/docs/channels/email) — `createMailer` / `createSMTPMailer`
 - [Runtimes](/docs/get-started/runtimes) — socket adapters
 

package/site/content/docs/transports/sndr.mdx

@@ -5,8 +5,12 @@ icon: Truck
 source: "src/transports/sndr.ts"
 ---
 
-Use SNDR when you want an HTTP email API for receipts, sign-in mail, and other app-triggered messages.
-Wire `SndrTransport` into `createMailer` — do not call the vendor SDK from application code.
+Use SNDR for app-triggered email — receipts, sign-in mail, and other transactional sends — over HTTPS JSON.
+Wire `SndrTransport` into `createMailer`; do not call `@rkiza/sndr` from application code.
+
+<LiveVerified>
+Email send against SNDR’s production API succeeded in sently’s opt-in live suite (verified domain + real recipient).
+</LiveVerified>
 
 <Callout title="The one rule">
   Import from `sently/transports/sndr`, pass the transport to `await createMailer(...)`, and send
@@ -55,7 +59,7 @@ console.log(result.messageId); // e.g. em_…
 console.log(result.response); // e.g. queued
 ```
 
-`from` must use a domain verified in the SNDR dashboard.
+`from` must use a domain verified in the [SNDR dashboard](https://www.sndr.sh/) (SPF, DKIM, DMARC).
 
 </Step>
 
@@ -82,10 +86,12 @@ console.log(result.response); // e.g. queued
 | `idempotencyKey` / `messageId` | `Idempotency-Key` | Sent when present. |
 | `data` | `variables` | Only when a template id is set. |
 
+`POST /v1/send` is idempotent when `Idempotency-Key` is supplied.
+
 ## Templates
 
 Set a template with the `x-sndr-template-id` header (or `defaultTemplateId` on the transport).
-Pass template variables through `data`.
+Pass template variables through `data` (`{{ variable }}` placeholders on SNDR).
 
 ```ts
 import { SNDR_TEMPLATE_ID_HEADER } from "sently/transports/sndr";
@@ -105,13 +111,57 @@ await mailer.send({
 
 Failed HTTP responses throw `SndrError` (`SentlyError`) with the API `error.message` when present.
 
+| SNDR `error.code` (common) | Meaning |
+| --- | --- |
+| `invalid_request` | Malformed payload |
+| `unauthenticated` | Missing or invalid API key |
+| `rate_limited` | Slow down |
+| `domain_not_verified` | Verify the sending domain first |
+| `recipient_suppressed` | Address is on the suppression list |
+
+## Webhooks
+
+Import from `sently/webhooks/sndr`. Verify `X-Sndr-Signature` (`t=…,v1=…`) over the **raw** body, then `parse`.
+
+| SNDR event | Normalized `EmailEvent.type` |
+| --- | --- |
+| `email.queued` | `deferred` |
+| `email.delivered` | `delivered` |
+| `email.bounced` | `bounced` |
+| `email.failed` | `unknown` |
+| `email.complained` | `complained` |
+| `email.opened` | `opened` |
+| `email.clicked` | `clicked` |
+| `email.unsubscribed` | `unknown` |
+
+See [Webhooks](/docs/guides/webhooks#sndr-signatures) for the HMAC details.
+
+## What sently covers vs SNDR platform
+
+| Surface | In sently | Notes |
+| --- | --- | --- |
+| Send (`POST /v1/send`) | Yes — `SndrTransport` | Channel: `createMailer` |
+| Templates + variables | Yes | Header / `defaultTemplateId` + `data` |
+| Idempotency | Yes | `idempotencyKey` / `messageId` |
+| Domain verify | Yes — `verify()` | `GET /v1/domains` |
+| Delivery webhooks | Yes — `sently/webhooks/sndr` | Signed parse |
+| Contacts / contact groups / broadcasts | No | SNDR dashboard / their API |
+| Analytics / suppressions admin | No | Use SNDR dashboard |
+| Attachments on HTTP send | Not mapped | Prefer SMTP or ask SNDR if their send API gains attachments |
+
 ## Troubleshooting
 
 <Accordions>
 
 <Accordion title="from domain is not verified">
 
-SNDR rejects sends from unverified domains. Verify DNS in the SNDR dashboard, then retry with that domain in `from`.
+SNDR rejects sends from unverified domains. Add SPF, DKIM, and DMARC in the dashboard Domains page, click Verify, then retry with that domain in `from`.
+
+</Accordion>
+
+<Accordion title="recipient_suppressed">
+
+The address is on SNDR’s suppression list (bounce/complaint). Remove it only if the recipient opted back in; otherwise pick another address.
 
 </Accordion>
 
@@ -129,6 +179,19 @@ No. Use `createMailer` plus `SndrTransport`. Keep vendor extras off the shared e
 
 </Accordions>
 
+## Contact & resources
+
+| Contact | Detail |
+| --- | --- |
+| Direct email | [sndr@rkiza.sa](mailto:sndr@rkiza.sa) |
+| Contact form | [sndr.sh/contact](https://www.sndr.sh/contact) |
+| Docs | [sndr.sh/docs](https://www.sndr.sh/docs) |
+| API reference | [API Reference](https://www.sndr.sh/docs/api-reference) |
+| Status | [sndr.sh/status](https://www.sndr.sh/status) |
+| X / Twitter | [@usesndr](https://x.com/usesndr) |
+| LinkedIn | [SNDR company](https://www.linkedin.com/company/104143949) |
+| GitHub | [github.com/rkiza/sndr](https://github.com/rkiza/sndr) |
+
 ## Learn more
 
 - [Email channel](/docs/channels/email) — mailer options and send pipeline