Skip to content

Transactional Email

Overview

Transactional Email sends operational messages tied to a workflow step: confirmations, receipts, notices, or document deliveries. You can send a message to one or more recipients, include a plain-text body and an optional HTML version, and attach files (PDFs, CSVs, exports) when the email must carry a document.

Key defaults and behavior

  • From name defaults to "Eos by PK4" unless you set a different From name.
  • From email uses the address you provide. If blank, it uses the configured sender address (SENDGRID_FROM). If that is not set, it falls back to noreply@eoshq.com.
  • Delivery uses SendGrid when SENDGRID_API_KEY is set. If not, and SMTP_URL is set, the system sends via SMTP (nodemailer). If a provider returns an error, the send fails with an error.

When to use Transactional Email

Use this when an email itself completes a business step rather than running a campaign:

  • Send a receipt, confirmation, or workflow notice.
  • Deliver a generated document (PDF, CSV) as an attachment.
  • Send the same operational message to several recipients.
  • Present a branded HTML view while including a plain-text fallback.

How it works

Choose recipients (To)

  • Enter one or more email addresses in To. The system trims input and removes blank entries.
  • At least one non-blank recipient is required.

Write the message

  • Subject: a concise subject line, e.g., “Receipt for Order 10482.”
  • Text: the plain-text body. Plain text is always included, so put all essential details here.
  • HTML: optional. If provided, HTML is included in addition to the plain-text body.

Set the sender

  • From email: set a specific sender address if needed; otherwise the configured sender or fallback address is used.
  • From name: set the display name; leaving it blank shows Eos by PK4.

Add attachments

  • Each attachment must include a filename and file content to be included.
  • Content may be provided as a Buffer or as raw bytes/strings; missing filename or content causes the attachment to be skipped.
  • If content type is not provided, it defaults to application/octet-stream.
  • When using SendGrid, attachments are sent base64-encoded.

Delivery providers and errors

  • If SENDGRID_API_KEY is present, the system calls SendGrid’s v3/mail/send endpoint.
  • If SENDGRID_API_KEY is absent and SMTP_URL is set, the system sends via SMTP (nodemailer).
  • If a provider returns an error (for example, SendGrid responds with a non-OK status), the send throws an error that includes the provider response status and body.

Typical workflow

  1. Add one or more recipients in To. Verify no required recipient is left blank.
  2. Write a clear Subject that summarizes the message.
  3. Compose the Text body so it stands alone if the recipient does not view HTML.
  4. Add HTML only when you need formatted presentation.
  5. Set From email and From name when the message must come from a specific identity.
  6. Attach required files. Confirm each attachment has a valid filename and content.
  7. Send and monitor for errors. If the send fails, resolve the provider issue or fix the message/attachments before retrying.

Fields, controls, and notes

  • To — Recipient email(s). Required. Blank or whitespace-only entries are removed.
  • Subject — Email subject line. Sent as text.
  • Text — Plain-text body. Always included.
  • HTML — Optional HTML body. Included when provided.
  • From email — Sender address. If blank, uses SENDGRID_FROM or noreply@eoshq.com.
  • From name — Sender display name. Defaults to "Eos by PK4".
  • Attachments — Files to include. Each attachment must provide a filename and content. Missing filename or content is ignored. Content type defaults to application/octet-stream when not supplied.

Things to watch for

  • The email will not send if To contains no non-blank recipient.
  • Paste operations that introduce blank lines are trimmed; verify pasted lists to avoid missing recipients.
  • Plain-text Text must convey the essential information even when HTML is present.
  • Attachments missing filename or content are skipped and will not be delivered.
  • Confirm SENDGRID_API_KEY or SMTP_URL is configured; otherwise delivery is unavailable.
  • If a provider responds with an error, the send fails and includes the provider’s response in the error message.