@softr/sdk 0.0.97-alpha.2 → 0.0.98-anonsession.0

package/skills/softr-sdk/email/SKILL.md

@@ -1,136 +0,0 @@
----
-name: email
-description: >-
-  Send an email from the app itself, with nothing to connect and no workflow:
-  defineEmailAction from @softr/sdk declares who may send it and the fields it
-  fixes (to, cc, bcc, replyTo, and an optional senderId); email.send from
-  @softr/sdk/server sends one with a subject and a text or HTML body, and throws
-  an EmailError with a code when Softr does not send it. Load this for a contact
-  form that emails the owner, a confirmation to the signed-in user, staff
-  emailing a client, or any email the app sends while handling what a person
-  does in it.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.97-alpha.2
----
-
-**Boundary.** `email` and `EmailError` live on `@softr/sdk/server` and run only inside a `createServerFn` handler — importing them into a component fails the build. `defineEmailAction` and every type come from `@softr/sdk` and can be imported anywhere.
-
-# Email
-
-An app sends an email through an email action. Softr sends it and bills the workspace's **workflow credits**, so there is no mail service to connect and no workflow to build. Use it for every email the app sends while it handles something a person does in it: a form submitted, a button pressed, a record saved through the app.
-
-A workflow is still the answer for an email on a schedule ("every Monday") or on a change made outside the app (a record edited in the table): load `automate-with-workflows` for those. A connected Gmail or Outlook is the answer only when the user wants the email to come from their own mailbox, through the `integrations` sub-skill.
-
-`defineEmailAction` missing from `@softr/sdk`? The app was built on an older version. Upgrade `@softr/sdk` to the latest version first, then write the action.
-
-## Who can send it, and to whom
-
-The action's `permissions` is its audience: everyone in it can send an email through it, directly, without the app's own code. The app's code is not a guard. Only what the declaration fixes holds whatever the caller sends.
-
-- **Fix the recipients whenever the use case allows.** A contact form that emails the owner fixes `to` to the owner. "Email me this report" fixes `to` to `{LOGGED_IN_USER:EMAIL}`. Then nobody can send the app's email to anyone else.
-- **When people pick the recipients, narrow the audience.** "Staff email a client" leaves `to` open and keeps the action to the staff group with `customGroups`. An action with open recipients for all signed-in users lets anyone who signs up send any email to anyone from the app's address, up to the workspace's credits. Build that only when the user asks for it, and tell them so in one line. An action open to visitors must fix `to`: one that fixes only `cc` or `bcc` is not stored.
-- **Recipients the person picks need the workspace's own sender.** An action that leaves `to` open must send from a confirmed sender, as its `senderId` or as the app's sender. From Softr's address every send fails with `SENDER_UNAVAILABLE`. Set the sender up before you write such an action, or ask the user which one to use.
-
-## The sender
-
-An email comes from the action's `senderId`, else from the app's email sender. With neither, it comes from Softr's own address, `"<workspace name>" <workspaceId@softr-email.com>`, the one workflows' "Send email with Softr" uses. That address is for testing: at most 30 emails a day per workspace, and the next one fails with `DAILY_LIMIT_REACHED`. The app's default `@softr.app` address sends only its sign-in emails.
-
-A chosen sender that is missing or not confirmed fails every send with `SENDER_UNAVAILABLE`. Softr never falls back to its own address.
-
-- While you build, list the workspace's senders with `workspace_list_email_senders`, and say which are confirmed, or that there are none.
-- With confirmed senders, and a plan that allows custom senders, ask the user which one the email comes from and set it as the action's `senderId`, copied exactly. Nothing else changes, sign-in emails included. Never pick one yourself.
-- With none, say the emails come from Softr's address, for testing and at most 30 a day. To send from their own address, they add one under the workspace's email senders and confirm the email it receives. Custom senders need the Professional or Business plan.
-- Read the app's sender with `application_get` before you say where the emails come from. Your closing message names the actual From address: the `senderId`'s, else the app's, else `<workspaceId>@softr-email.com` with the real id. Never write "if no sender is set": read it.
-- Changing the app's sender also changes the address its sign-in emails come from. Call `application_configure_email_sender` only when the user wants the app's sender changed, after naming both effects.
-- Confirming the email is all an email action needs. The domain's DNS records (DKIM, Return-Path) are needed only before Studio lets the app pick the address as its own sender, and they help the emails stay out of spam.
-
-## What it costs
-
-Every email costs **5 workflow credits per recipient**, from the workspace's monthly workflow credits, which its workflows spend too. You do not know the workspace's plan, so never name one or count how many emails it covers. The plan and the closing message give the cost and where to watch it, for example: "Each submission emails you, at 5 workflow credits per email. Track them in Settings → Billing → Workflow usage, where this app has its own row."
-
-Emails sent from the preview are real and charged, and the actions in the code reach the live app as soon as they are saved. Send at most one test email, and only when the user asks for one. Never send emails in a loop to try something out.
-
-## Declare the action
-
-```ts
-const notifyOwner = defineEmailAction({
-  id: 'notifyOwner',
-  to: ['owner@acme.com'],
-  permissions: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] },
-})
-
-const emailClient = defineEmailAction({
-  id: 'emailClient',
-  replyTo: '{LOGGED_IN_USER:EMAIL}',
-  permissions: { userGroupTypes: ['LOGGED_IN_USERS'], customGroups: ['<the staff group id>'] },
-})
-```
-
-- `id` is a name you choose, unique across the app.
-- `to`, `cc`, `bcc`: arrays of addresses. Each one declared here replaces the call's, and declaring `to` also ignores the call's `cc` and `bcc`. An element may be a whole placeholder for the signed-in sender: `{LOGGED_IN_USER:EMAIL}`, or `{LOGGED_IN_USER:<field>}` for an email field of their user record. Never part of a string, never in the call.
-- `replyTo`: an address or one such placeholder.
-- `senderId`: one of the workspace's senders, as above. The call can never set the sender.
-- `permissions`: who may send it, as for queries and mutations.
-
-Write the object inline in `defineEmailAction`, every value a literal. A declaration that cannot be read is not stored, and the check reports it.
-
-Declare one action per kind of email: the owner's notification and the client's confirmation are two actions, each with its own recipients and audience.
-
-## Core pattern
-
-```ts
-const submit = createServerFn({ method: 'POST' })
-  .validator(contactSchema)
-  .handler(async ({ data }) => {
-    const saved = await ds.create(saveSubmission, { data })
-    try {
-      await email.send(notifyOwner, {
-        subject: `New message from ${data.name}`,
-        body: renderSubmission(data),  // the app's own HTML, with what the visitor typed escaped
-        replyTo: data.email,
-      })
-    } catch (error) {
-      if (error instanceof EmailError) return { saved: true, emailed: false, reason: error.message }
-      throw error
-    }
-    return { saved: true, emailed: true }
-  })
-```
-
-`email.send(action, init)` takes:
-
-- `subject` and `body`. Required. `body` is plain text or HTML. Escape what visitors typed before you put it into HTML.
-- `to`, `cc`, `bcc`, `replyTo`: each used only where the action does not fix it, and `cc` and `bcc` never when it fixes `to`. Each entry is one address. At most 50 recipients per email.
-
-It answers `{ messageId }` once the email is sent. The answer never lists the recipients. An email carries no attachments: link to the file instead.
-
-Every call is a new email. Disable the button while the request runs, so a double click does not send twice.
-
-## Failure modes
-
-**Not handling `EmailError`.** `email.send` throws an `EmailError` from `@softr/sdk/server`, with `status`, `code` and `message` when the email was not sent, and never retries by itself. Catch it, keep what the request already saved, and show the person a line they can act on: "Saved, but the email could not be sent." The codes:
-
-| `code` | Meaning |
-| --- | --- |
-| `NOT_FOUND` | No such action, or the caller is not in its audience |
-| `INVALID_INPUT` | No subject or body, an entry or placeholder that is not exactly one address, or more than 50 recipients |
-| `PLAN_RESTRICTED` | The workspace's plan does not allow this email |
-| `CREDITS_EXHAUSTED` | The workspace has no workflow credits left |
-| `RATE_LIMITED` | The app sent too often lately. Tell the person to try again later |
-| `DAILY_LIMIT_REACHED` | Softr's own address sent its 30 emails for today. Tell the person the email could not be sent today; the owner fixes it by choosing their own sender |
-| `SENDER_UNAVAILABLE` | The chosen sender is missing or not confirmed, or the action leaves `to` open and has no sender of the workspace's own. Tell the person the email could not be sent; the owner fixes the sender |
-| `PROVIDER_REJECTED` | The mail provider refused the email |
-| `UNAVAILABLE` | Softr could not send it right now or could not be reached |
-| `TIMEOUT` | No answer in time. It may still have been sent, so never send it again by yourself |
-
-**Letting a mistyped address reach Softr.** An address the person typed (the reply-to of a contact form, a client's email) that is not one address is refused with `INVALID_INPUT`, which reads as a vague failure. Check its format in the validator and tell them which field is wrong.
-
-**Calling from client code.** `email` is server-only. Wrap the send in a `createServerFn` and call that from the form or the button.
-
-**Taking recipients from the request when they could be fixed.** A `to` the browser sends is a `to` any caller can change. Fix it in the declaration, or read it on the server from the record the email is about.
-
-**Placeholders in the call.** `{LOGGED_IN_USER:EMAIL}` is filled only in the declaration. In the call it is sent as written and fails.
-
-**Building a workflow for an email the app sends itself.** A "Run custom workflow" trigger plus a "Send email" step does the same at more cost to the user: a workflow to keep published. Use the email action; keep workflows for schedules and table events.