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
- Add one or more recipients in To. Verify no required recipient is left blank.
- Write a clear Subject that summarizes the message.
- Compose the Text body so it stands alone if the recipient does not view HTML.
- Add HTML only when you need formatted presentation.
- Set From email and From name when the message must come from a specific identity.
- Attach required files. Confirm each attachment has a valid filename and content.
- 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.
Related areas
- Email provider configuration
- Operational notifications
- Document delivery workflows
- Outbound communications governance