Attached is the latest quarterly sales report.
" }, "attachments": [ { "filename": "q2-sales-report.pdf", "content_type": "application/pdf", "upload_ref": "upl_abc123" } ], "metadata": { "workflow": "quarterly-report", "run_id": "run_789" } } ``` A few implementation notes matter more than the fields themselves: - **Use attachment references, not file blobs:** The send call should point to an already uploaded object. - **Include workflow metadata:** Agents need traceability. Metadata helps correlate sends with jobs, prompts, reports, and downstream actions. - **Store both text and HTML when you can:** Plain text is useful for fallback and downstream processing. ### SDKs and CLIs are useful when they stay thin I like SDKs when they remove boilerplate without hiding the model. The same applies to a CLI. Both are helpful for testing mailbox behavior, replaying sends in staging, and validating attachment flows during development. An SDK version of the same operation usually looks like this in spirit: ```javascript await client.messages.send({ mailboxId: "mbx_123", to: [{ email: "finance@example.com", name: "Finance Team" }], subject: "Quarterly sales report", text: "Attached is the latest quarterly sales report.", html: "Attached is the latest quarterly sales report.
", attachments: [ { filename: "q2-sales-report.pdf", contentType: "application/pdf", uploadRef: "upl_abc123" } ], metadata: { workflow: "quarterly-report", runId: "run_789" } }); ``` And a CLI invocation often makes sense for smoke tests: ```bash mail send \ --mailbox mbx_123 \ --to finance@example.com \ --subject "Quarterly sales report" \ --text "Attached is the latest quarterly sales report." \ --attachment-ref upl_abc123 ``` The exact syntax varies by platform. The pattern shouldn’t. Here’s a short visual walkthrough before going further. ### What to avoid when you send email with attachments The failure modes are predictable. Most come from trying to collapse upload, formatting, and delivery into one step. - **Don’t base64 everything by default:** You’ll inflate payload size and make retries more expensive. - **Don’t hide attachment generation inside the send call:** Generate first, validate second, send third. - **Don’t treat outbound email as stateless:** If the message belongs to a workflow, attach identifiers that help you recover context later. > Build the send endpoint so an agent can call it repeatedly and safely. If a retry creates duplicate messages or orphaned attachments, the contract is too loose. ### One clean model beats ten helper scripts Purpose-built email infrastructure helps. Robotomail’s published product description says agents can create mailboxes by API, send mail with a POST request, handle attachments with secure uploads and presigned URLs, and receive inbound messages through webhooks, polling, or server-sent events. That model is aligned with how agents operate because mailbox state, file state, and conversation state live in the same system. Whatever platform you choose, that’s the bar. If you need one service for mailbox creation, another for file storage, a third for outbound delivery, and custom glue for replies, you’re building your own mail platform whether you meant to or not. ## Ensuring Security and High Deliverability Teams usually treat security and deliverability as cleanup work after the send call works once. That’s how attachment systems become flaky. If your agent sends files at scale, these aren’t secondary concerns. They determine whether the workflow is usable at all. ### Oversized files break more than one thing When an attachment is too large, the obvious failure is a rejected message. The less obvious failures are worse. Queues back up. Retry jobs churn. Agents keep regenerating documents that still won’t send. Recipients get duplicate notices with missing files. That’s not hypothetical. **Automated sending campaigns see a 22% bounce rate from oversized attachments alone, and that figure has risen 15% year over year as AI-generated reports get larger**, according to [SSW’s summary of large-attachment constraints and sending failures](https://www.ssw.com.au/rules/avoid-large-attachments-in-emails). ### The right guardrails are strict and boring Good attachment systems reject bad sends early. They don’t hope the downstream provider will sort it out. A production policy usually needs: | Control | Why it matters | Good default behavior | |---|---|---| | Attachment size validation | Prevents avoidable bounces | Reject before send and return a clear error | | Per-mailbox rate limiting | Protects sender reputation and prevents loops | Slow or stop bursty agent behavior | | Suppression handling | Avoids repeated sends to bad destinations | Block further sends after hard failures | | Storage quotas | Prevents attachment buildup from becoming invisible debt | Expire or archive according to policy | ### Authentication and message trust still matter Attachment handling sits inside a broader email trust model. If your platform supports custom domains, sender authentication should be part of the managed setup, not a side quest for the application team. Published product information for Robotomail says it supports custom domains with auto-configured DKIM, SPF, and DMARC, plus HMAC-signed webhooks for integrity. Those details matter because agents don’t just send mail. They react to inbound events, and those events need to be verifiable. > A message pipeline is only as trustworthy as its inbound verification. If you act on replies without signature checks, you’re letting anyone simulate your users. ### Error handling should map to agent behavior A normal app can show a red banner and wait for a person. An agent can’t. It needs explicit policies for each class of failure. Some examples: - **If upload fails:** Retry the upload, not the full workflow, and log the file-generation step separately. - **If send fails due to size:** Replace the attachment with a secure file link or split the workflow into a summary email plus retrieval path. - **If the recipient address hard-bounces:** Stop retrying and update the task state so the agent doesn’t keep hammering the same destination. - **If the provider rate-limits the mailbox:** Queue the job and preserve ordering for thread continuity. ### What actually improves deliverability Developers tend to think deliverability is mostly about copy quality or domain reputation. For attachment-heavy workflows, it’s also about mechanical discipline. Smaller bodies, valid sender authentication, predictable rates, and attachment policies do more than clever template tweaks. The practical takeaway is blunt. If your system lets any model-generated report attach itself to any outbound email with no validation, no limits, and no fallback path, your delivery problems are self-inflicted. ## Building Autonomous Workflows with Email Attachments The most useful way to think about attachments in agent systems is as a workflow, not as a send feature. The send call is one event in a longer chain that starts with a trigger and ends with a business action.  Many tutorials still miss this. **A major gap in current documentation is that 85% of top-ranking tutorials focus on manual file reading and MIME encoding while ignoring agent-native patterns such as presigned URL generation, secure uploads without OAuth, and automated threading**, as noted in [Microsoft’s attachment-sending quickstart context cited in the verified research set](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/email/send-email-advanced/send-email-with-attachments). ### A realistic agent scenario Take a quarterly reporting workflow. A sales operations agent runs every Monday morning after data refresh. Its job is to assemble a PDF summary for a list of stakeholders, send the report, and wait for replies requesting revisions or deeper breakdowns. This kind of workflow shows up in LangChain, CrewAI, and AutoGen projects all the time. The agent isn’t just “sending an email.” It’s coordinating document generation, storage, delivery, and response handling as one unit of work. If you’re operationalizing these systems across teams, broader planning around [AI Implementation](https://movetoclosedwon.com/ai-implementation/) is worth reviewing because attachment workflows expose all the usual rollout issues at once: permissions, observability, human override, and reliability. ### The six-step flow that holds up Here’s the pattern I’ve seen work consistently. 1. **A trigger starts the job** The trigger might be a scheduler, a CRM event, or an inbound request from another service. The important part is that the job gets a durable run ID before any file is generated. 2. **The agent generates the attachment** It creates the PDF, CSV, invoice bundle, or image. This output should be treated as an artifact with metadata, not as a temporary string living inside the model runtime. 3. **The system uploads the file securely** The app requests a presigned upload target, stores the artifact, and records the upload reference. Virus scanning, file policy checks, and retention rules belong here. 4. **The agent sends the email** The message references the uploaded file. It also includes workflow metadata so later replies can be tied back to the exact job. 5. **The platform monitors delivery and replies** The app receives status events and inbound messages through a verified channel. No polling inboxes manually. No scraping an IMAP folder if you can avoid it. 6. **The agent reacts** If a stakeholder replies “send the regional split too,” the agent has enough context to generate a follow-up and attach the next file in the same thread. ### What the code orchestration usually looks like The application layer doesn’t need to be fancy. It just needs clean boundaries. - **Planner step:** Decide who should receive the email and what file must be generated. - **Generator step:** Produce the report and save it locally or in transient storage. - **Uploader step:** Move the artifact to the secure attachment store and receive an upload reference. - **Mailer step:** Send the message with subject, body, recipients, and attachment reference. - **Listener step:** Handle delivery events and inbound replies. - **Resolver step:** Update the original task or create the next one. That structure is much healthier than letting the agent improvise every operation directly. The model can choose content and intent. Deterministic code should own file handling, sending, and security checks. > Let the model decide what to send. Don’t let it decide how attachment security works. ### Threading is where the workflow becomes usable Without threading, every reply becomes a classification problem. You have to infer what the recipient is responding to, match subjects, parse quoted text, and hope the timing lines up. With automatic threading, the system already knows the reply belongs to the original outbound message. That gives your agent a stable conversation object. It can retrieve the prior attachment list, understand the last action taken, and generate the next response with context intact. ### A short example of agent behavior Suppose the stakeholder replies, “Need the same report with EMEA broken out separately.” A solid workflow does this: | Step | Agent action | |---|---| | Reply received | Verify webhook signature and parse thread context | | Context lookup | Find the original report job and recipient history | | New artifact generation | Produce the EMEA-specific PDF | | Upload | Store the new PDF through the secure upload path | | Response | Send a threaded reply with the new attachment | | Audit | Record the follow-up action in logs or task state | The weak version of this workflow does something very different. It treats the reply as a fresh inbound message with no context, regenerates too much state, and often loses the relationship between the new document and the old one. ### Why this model scales better Agent stacks get messy when every framework component talks directly to email infrastructure. The cleaner approach is to expose a narrow mail capability to the agent and keep attachment handling in deterministic service code. That lets you swap models, adjust prompts, or change orchestration frameworks without rewriting your mail path. That’s also why “send email with attachments” is not a single function in a serious agent system. It’s a compact workflow with state, policy, and event handling around it. ## Closing the Loop Processing Inbound Replies with Webhooks Sending the message is only half the job. If the recipient replies with approval, a question, or a revised file, your agent needs that inbound event immediately and safely. Polling an inbox every few minutes works for prototypes. It’s the wrong default for production.  ### Webhooks are the right integration surface When a new inbound message arrives, the mail platform should push an event to your application. That lets the agent react while the conversation is still fresh and while workflow context is still resident in your systems. If you need a reference model, the [Robotomail webhook concepts documentation](https://robotomail.com/docs/concepts/webhooks) outlines the sort of event-driven interface you want to see: inbound notifications tied to mailbox activity rather than a bolt-on inbox sync. For teams comparing event architectures across products, Administrate’s overview of [advanced webhook capabilities](https://administrate.dev/features/webhooks) is a useful cross-check for what mature webhook systems should provide around payload delivery and integration behavior. ### Verify the HMAC signature every time This is the step teams skip because the webhook “works” without it. Don’t skip it. Your endpoint should verify the HMAC signature on every incoming event before you parse the payload or trigger any agent action. If the signature doesn’t match, reject the request and log it. That one check is what prevents arbitrary external callers from pretending to be your mail provider and injecting fake approvals, fake attachments, or fake customer responses into your system. A minimal inbound handler usually does four things in order: 1. **Read the raw request body** 2. **Compute the expected HMAC with your shared secret** 3. **Compare it to the signature header using a constant-time check** 4. **Only then parse and process the event** > **Security note:** Signature verification belongs before business logic, before JSON parsing shortcuts, and before any side effects. ### Preserve conversation context through threading Inbound email is messy. Subjects drift. People forward messages. Mobile clients rewrite formatting. If your provider preserves threading automatically, use that thread identifier as the primary conversation key. That gives the agent a much better working context: - **Original outbound message:** What was sent and which attachment was included. - **Recipient identity:** Who replied and whether they’re expected to participate. - **Current workflow state:** Was the last action “awaiting approval,” “awaiting revision,” or “completed”? - **Attachment chain:** Did the recipient send a replacement file or request a new one? ### A clean webhook processing pattern Keep the handler itself thin. It should verify authenticity, acknowledge receipt, and hand the payload to a job processor. A reliable pattern looks like this: | Layer | Responsibility | |---|---| | Webhook endpoint | Verify signature, validate schema, return fast | | Event queue | Buffer transient spikes and retries | | Worker | Parse reply, fetch thread context, decide next action | | Agent service | Generate response or trigger a downstream task | | Audit log | Record what happened and why | That separation matters because inbound email isn’t deterministic. Some replies are clean approvals. Some are out-of-office notices. Some include new attachments. Some contain a one-line “looks good” buried above a quoted thread. You want deterministic code handling transport and authenticity, and the agent handling the semantic part. ### What a complete loop looks like A stakeholder receives a report, replies with edits, and attaches a revised spreadsheet. Your webhook receives the event, verifies the HMAC signature, identifies the thread, stores the new file, and passes the context to the agent. The agent reads the reply, recognizes it as a revision request, and triggers the next workflow step. That’s when email becomes useful for autonomous systems. Not when the app can send a PDF once, but when it can maintain a real conversation around that file without a human babysitting the inbox. --- If you need email infrastructure that matches agent workflows, [Robotomail](https://robotomail.com) is one option built around that model. It provides programmatic mailboxes, outbound sending, inbound handling, automatic threading, secure attachment uploads with presigned URLs, and HMAC-signed events, which is the shape you want when your agent has to send email with attachments and then keep the conversation going.