Automating Shopware Document Dispatch: Sending API-Created Documents to Customers

Automating Shopware Document Dispatch: Sending API-Created Documents to Customers

In the dynamic world of e-commerce, efficiently managing order documents like invoices, delivery notes, and credit memos is crucial. For Shopware 6 merchants and developers relying on API integrations for order processing, a common challenge arises: how to automatically send documents created or uploaded via API to customers and ensure they are correctly marked as "sent" within the Shopware administration. This community insight, drawn from a recent Shopware forum discussion, provides a direct and efficient solution.

The Challenge: API-Generated Documents Not Sending Automatically

A user on the Shopware forum, c.rosenberger, highlighted a pertinent issue: after creating or uploading order documents via the Shopware API, these documents were neither automatically dispatched to the customer nor marked with the "sent" status in the backend. This situation typically necessitates manual intervention or the development of custom plugins, which can be time-consuming and add unnecessary complexity, especially when dealing with specific Shopware versions like 6.7.13.1 where the V2 DocumentGenerator might not be fully integrated or preferred.

The core question was whether a custom plugin, perhaps a DocumentGenerator Decorator, was the only viable path forward for automating this process.

The Solution: Leveraging Shopware's Native Mail API

Fortunately, as expert b.david clarified in the forum, there's no need for a custom plugin or a DocumentGenerator Decorator for this specific task. Shopware inherently marks documents as "sent" once they are successfully dispatched as attachments through its internal mail sending mechanism. The key lies in utilizing the correct API endpoint that the Shopware administration itself uses for sending documents.

The solution involves a simple yet powerful API call:

• After a document has been created or uploaded (e.g., an invoice generated by an external system and then uploaded to Shopware), you can trigger its dispatch.
• Make a POST request to the /api/_action/mail-template/send endpoint.
• Crucially, include the documentIds of the documents you wish to send within the request payload.

API Request Example

Here’s the structure of the JSON payload required for the POST /api/_action/mail-template/send endpoint:

{  "mailTemplateId": "",  "recipients": { "[email protected]": "Max Mustermann" },  "salesChannelId": "",  "subject": "...",  "senderName": "...",  "contentHtml": "...",  "contentPlain": "...",  "mailTemplateData": { "order": { "id": "" } },  "documentIds": [""]}

Explanation of Key Fields:

• mailTemplateId: The ID of the email template you want to use (e.g., for invoices, order confirmations, etc.).
• recipients: An object containing the recipient's email and name.
• salesChannelId: The ID of the sales channel associated with the order.
• subject, senderName, contentHtml, contentPlain: These fields define the email's subject, sender, and body. For convenience, you can retrieve these values from an existing mail template via the /api/search/mail-template endpoint.
• mailTemplateData: An object containing data relevant to the mail template, such as the order ID, which allows the template to populate dynamic content.
• documentIds: This is the critical field. It's an array of document IDs that Shopware will attach to the email. Once the mail is successfully sent with these attachments, Shopware automatically sets the sent = true flag on these documents.

Important Considerations and Troubleshooting

While this API approach simplifies automated document sending, there are a few best practices and troubleshooting tips to keep in mind:

• Loading Template Data: To avoid manually crafting the email content, subject, and sender name, it's highly recommended to first fetch the desired mail template using /api/search/mail-template. This ensures consistency and leverages your existing Shopware email configurations.
• Error Logging: If an email fails to send, Shopware might silently discard template-related errors without reporting them directly back to the API. Always check your Shopware logs for entries like mail.sent.error to diagnose any issues. This can help identify problems with email templates, missing data, or mail server configurations.
• "Sent" Status: The automatic marking of documents as "sent" (sent = true) is a core benefit of this method, providing clear tracking within the Shopware backend without additional logic.

Conclusion

Automating the dispatch of API-generated order documents in Shopware 6 is a straightforward process that doesn't require complex custom development. By understanding and utilizing the POST /api/_action/mail-template/send endpoint with the appropriate documentIds, developers and integrators can streamline their workflows, ensure timely communication with customers, and maintain accurate document status tracking within Shopware. This approach underscores Shopware's robust API capabilities for comprehensive e-commerce management.