Overview
Build an Email Admin Workspace. This written companion follows the same sequence as the narrated video. It explains the workflow and validation steps; it does not supply a complete production application or claim a live deployment was performed.
Define the email workspace
An email administration component is more than a text box and a send button. Define composing, previewing, sending, and history as separate states. Receiving mail is another integration and does not appear automatically because outbound SMTP works. Require an authenticated administrator for the workspace and each backend operation. Start with a narrow transactional or direct-message workflow, then add mailbox ingestion, attachments, and automation once the basic send lifecycle can be explained and tested.
Map the server boundary
The browser collects composition input, while the server owns credentials, validation, template rendering, and delivery requests. Keep SMTP passwords and provider keys out of the client bundle. The database stores the intended message and its known outcome so a page refresh does not erase the operational record. A successful HTTP request is not itself evidence that the recipient received mail. Return an explicit application status that distinguishes validation, provider acceptance, and an uncertain outcome.
Model a composition before generating HTML
Use a structured composition model instead of accepting unrestricted HTML as the default editing format. A subject, heading, paragraphs, and optional link are easier to validate and render consistently. Include a useful plain-text version for clients that do not display HTML. Keep the sender identity under server control so a caller cannot impersonate arbitrary addresses. The same composition model can later support a native app without duplicating every template rule in a second frontend.
Validate recipients and visibility
Decide which address syntax the product supports and validate it consistently. Deduplicate recipients and bound the count before sending. When recipients should not see one another, use a private delivery approach and test the final message headers. A shared recipient list should be an explicit choice. Separate messages are often better for personalized content or per-recipient preferences. Do not assume that hiding an address in the interface means it is absent from the generated email headers.
Define the identity boundary
The browser collects credentials but the server decides whether they are valid. Keep user records and password hashes in the database, and return only the profile fields the interface needs. A successful login creates a new server session. Don't use a hidden page or a Boolean stored in the browser as your access control. Every protected request must be checked independently.
Create a fresh session
After verifying the credentials, generate a fresh unpredictable session token. Save its digest on the server and send the original only in the session cookie. The cookie settings shown are for secure deployment. The database must enforce the expiry as well as the browser's cookie lifetime. Rotate the session when the user logs in, and revoke the previous identifier instead of reusing it.
Protect reads and mutations
Authentication middleware should resolve the session and reject expired or revoked entries before a handler accesses private records. State-changing routes also need a suitable request forgery defence, such as a correctly enforced origin policy and token strategy for your architecture. Add rate limits and monitoring around authentication. Never treat a cookie's presence alone as proof that a valid session exists.
Authorize the send route
Protect the server route independently of the admin page. Check the current session and required role before processing a potentially large composition. Apply appropriate request-origin and cross-site protections for the authentication mechanism in use. Bound the request body even when a content-length header is missing or inaccurate. Do not accept arbitrary server filesystem paths or sender identities from the client. Interface navigation is a convenience, while the route is the actual trust boundary.
Configure SMTP on the server
Configure the provider connection in the server environment and use the TLS mode required by that provider. Implicit TLS and an explicit upgrade to TLS are different connection modes, so a port number and secure flag must agree with the documented service. Require encryption where the provider supports the expected upgrade rather than silently falling back to plaintext. Keep connection timeouts bounded. Verifying a connection checks a useful prerequisite, but it does not prove delivery of a particular message.
Verify the sending domain deliberately
Use a sending identity you control and follow the provider's domain-verification instructions. DNS records are specific to the chosen domain and service, so do not copy another site's values. Understand the distinction between the visible From address and the envelope sender when evaluating authentication. Inspect the received message's authentication results during a controlled test. A verified domain improves the foundation, but it does not guarantee inbox placement or replace relevant, wanted message content.
Create history before the send attempt
Record the intended operation before contacting the provider. If the history write fails, stop instead of creating a message that the application cannot track. After the provider responds, update the record with the known outcome and identifier. The database and external provider are separate systems, so there is a failure window between them. Design the interface around that uncertainty rather than claiming that one ordinary database transaction can atomically commit both systems together.
Distinguish acceptance from delivery
Use status names that describe what you actually know. SMTP acceptance means a server accepted responsibility for the message, not that it appeared in the recipient's inbox or was read. Some recipients may be accepted while others are rejected. If the connection fails after transmission, the outcome may be uncertain. Preserve those distinctions in history and user feedback. Avoid displaying a generic sent checkmark that encourages a blind retry when the provider may already have accepted the message.
Do not blindly retry an uncertain send
A timeout is not always proof that no email was sent. If transmission may have completed, repeating the request can produce duplicates. Record the uncertainty and use provider identifiers or supported idempotency features to reconcile where possible. Keep any idempotency assumptions specific to the provider and operation; a Message-ID header alone does not guarantee deduplicated delivery. Make the user interface explain why an unconfirmed message needs inspection instead of automatically resending it indefinitely.
Render safe HTML and plain text
Escape inserted text and validate links before rendering the final email. Do not turn an administrator's pasted content into arbitrary executable markup in the browser preview. Generate the plain-text alternative from the same composition so essential information is not lost. Email clients vary in layout support, image handling, and dark-mode behaviour, so describe the preview as an approximation. Test representative clients with controlled accounts before relying on a complex layout for important notifications.
Bound attachments at every layer
Attachment limits exist at several layers: the browser request, reverse proxy, application decoder, provider message, and receiving server. Base64 and MIME encoding increase the transmitted size, so a nominal file-size limit cannot be treated as the final email size. Validate the decoded bytes and supported types, and avoid loading unbounded content into memory. Reject executable or unsupported content according to the product policy. Be explicit that checking an extension is not a malware scan.
Keep inline images private by design
Inline images can be attached as referenced message parts instead of being published to a public URL. Validate image dimensions and decoded size before preparing them, since a small compressed file can still require substantial memory. Keep meaningful text available when an email client blocks images. Distinguish a decorative image from an ordinary downloadable attachment. The current CodeKits implementation has specific evolving limits, so a tutorial should teach how to configure those limits rather than presenting an old number as universal.
Protect stored history and access
Sent history can contain private addresses, message content, and attachment information. Apply authorization to every list, detail, and attachment endpoint. Store only what the operational workflow needs and define retention rather than accumulating everything indefinitely by accident. If encrypting stored content, protect the keys separately and plan rotation and recovery. Encryption does not replace access checks. Avoid putting full message bodies into general application logs where a broader group of people may have access.
Treat inbound email as a separate input
Receiving email requires a separate provider or mailbox integration. Verify incoming event authenticity and deduplicate repeated notifications before creating records. Treat the message as untrusted content, even when the sender display name looks familiar. Sanitize its presentation, handle attachments through controlled routes, and avoid automatically loading remote images that can track viewing. Build reply and forward actions from safe content. An inbound address should not become an unauthenticated command channel into the administration system.
Test without sending real messages
Test composition and state transitions with a fake transport before using a live provider. Inspect the generated message headers and MIME structure to verify recipient privacy, text alternatives, and attachments. Simulate partial acceptance, explicit rejection, and uncertain outcomes. Confirm that unauthorized or invalid requests never reach the transport. These offline checks establish application behaviour, not inbox delivery. A separate controlled integration test is needed to evaluate the configured provider and actual receiving accounts.
Use the CodeKits implementation as a reference
The existing CodeKits workspace provides concrete examples of composition, private and shared recipients, server-rendered templates, and sent-history outcomes. Its documentation distinguishes provider acceptance from inbox delivery and records why uncertain outcomes should not invite blind retries. The offline regression tests exercise recipient handling, MIME, privacy, and failures without sending live messages. Use these patterns as reference points, while reviewing the current source for actual limits and behaviour instead of copying older documentation values uncritically.
Write a permission matrix
Start with a small permission matrix based on real actions. Authentication tells you who is making the request; authorization decides whether that person can perform it on a particular record. Avoid broad role labels with unclear meaning. Write down the default denial behaviour, and identify operations that need additional review, such as assigning roles or accessing another person's data.
Keep roles under server control
Read role information from trusted server state. A public registration form must not be able to assign its own administrator role. If permissions are cached inside sessions or tokens, define how quickly role changes take effect. For sensitive applications, check the current role or a revocation version on each protected request. Changing a button's visibility doesn't change the server's decision.
Verify the complete admin workflow
Finish by following the full workflow with a controlled test message. Verify that draft validation, preview, send state, and history agree about the outcome. Refresh the browser during an attempt and confirm that the operation remains understandable. Attempt to open history and attachment records from an unauthorized account. Keep provider integration tests separate from offline checks, and do not claim inbox delivery from a mocked transport result or a screenshot of a success notification.
References and next steps
For help implementing or operating the project, see CodeKits development services.