New endpoint in orders/{id}/actions to send email #54597
Conversation
This revamps the existing OrdersActionsRestController and adds some
additional endpoints:
* A GET endpoint at orders/{id}/actions/email to get a list of email
templates that can be sent for this particular order.
* A POST endpoint at orders/{id}/actions/email where you can trigger
the sending of an email template for a particular order.
This also adds some other new things:
* A helper method for adding or updating the billing email of the order.
* Filter and action hooks so that extensions that register additional
email templates can include them in the list of available templates
for an order.
Initially this new functionality was going to be added as an entirely
separate endpoint, but after reviewing the existing functionality in
the `send_order_details` order action, we decided that this would fit
better, and allow us to have less duplicated code, if we just expanded
the existing endpoint.
Fixes #53810
|
Apart from reviewing the code changes, please make sure to review the testing instructions and verify that relevant tests (E2E, Unit, Integration, etc.) have been added or updated as needed. You can follow this guide to find out what good testing instructions should look like: |
Test using WordPress PlaygroundThe changes in this pull request can be previewed and tested using a WordPress Playground instance. Test this pull request with WordPress Playground. Note that this URL is valid for 30 days from when this comment was last updated. You can update it by closing/reopening the PR or pushing a new commit. |
There was a problem hiding this comment.
Nice work @coreymckrill 👏
I've left a couple of review comments and also this small thing I found about the testing steps:
On step 6. Try sending an email for the order using POST wc/v3/orders/{order ID}/actions/send_email. You should get a message back saying "Order does not have an email address.", I'm getting:
{
"code": "rest_missing_callback_param",
"message": "Missing parameter(s): template_id",
"data": {
"status": 400,
"params": [
"template_id"
]
}
}I'm only getting the "Order does not have an email address." when I send the template_id in the request body, I think that's correct right? It's the test step that needs to be updated.
plugins/woocommerce/src/Internal/Orders/OrderActionsRestController.php
Outdated
Show resolved
Hide resolved
|
👍 Thank you again! This adds comprehensive emailing capabilities that I'm excited to see! ✅ I tested all the scenarios and they work as described! I also tried to model these new APIs within our current IPP/POS flows. This is how I imagine they could be integrated in the beginning: 🟢 Succesful paymentMerchant selects "Email Receipt", and enters an email address. We send: PATH: Optionally, we would immediately pass It sends a “Thanks for shopping with us” email. The same one is sent if customer's email is attached to the order before the payment. 🔴 Failed paymentSame flow. Merchant selects "Email Receipt", and enters an email address. We send an email with a different template: PATH: It sends "Sorry, your order was unsuccessful” email QuestionThese flows would depend on hardcoded
As a designer of this API, do you think it's reasonable to hardcode template_ids? We would like to avoid making another API call, especially if it doesn't add additional functionality. I do imagine additional flows, that could utilize |
|
@albarin sorry, forgot to mention that I also updated the testing instructions from your feedback. Does it look better now? |
I was assuming that there would be a time somewhere in the mobile app flow where you would GET the order data and could store the available template IDs for future use. 🤔 But maybe that wouldn't always be the case? One easy thing we could do here is add an enum to the schema for the
I don't think hardcoding the template ID values is necessarily problematic, you're probably already doing that with other things like order statuses? But, because this new endpoint is extensible, and other extensions such as WooPayments could add their own email templates to the list, you'd probably still want to have a flow somewhere that retrieves the list just to see what's available. |
|
Ok, I added the enum to the schema... |
Yes, it's more likely we prefer to cache available email templates rather than rely on additional calls during the payment process. Unless we update our flows to let the merchant pick a desired template, we will still need to decide within the code which templates we want to send at which moment in time. Therefore, having hardcoded template_ids within the code will be hard to avoid. The ability to fetch all available or all template IDs allows to add of an extra layer of stability to the solution.
Yes. I think what this endpoint opens up - the ability to have a more comprehensive emailing functionality from within the app. That's where the functionality to fetch templates with their titles and allow merchants to pick the desired one could be a nice addition. |
Changes proposed in this Pull Request:
This revamps the existing OrdersActionsRestController and adds some additional endpoints:
orders/{id}/actions/email_templatesto get a list of email templates that can be sent for this particular order.orders/{id}/actions/send_emailwhere you can trigger the sending of an email template for a particular order.This also adds some other new things:
Initially this new functionality was going to be added as an entirely separate endpoint, but after reviewing the existing functionality in the
send_order_detailsorder action, we decided that this would fit better, and allow us to have less duplicated code, if we just expanded the existing endpoint.Fixes #53810
Post-merge
send_order_detailsendpoint, and about embedded data inordersendpointHow to test the changes in this Pull Request:
GET wc/v3/orders/{order ID}_linksproperty, and find the newemail_templatesitem within it.email_templateslink (GET wc/v3/orders/{order ID}/actions/email_templates). You should get back an empty array, because the order doesn't have a billing email set yet, so there are no email templates available to send.POST wc/v3/orders/{order ID}/actions/send_email. You'll need to include a template ID in the payload:{"template_id": "customer_invoice"}You should get a message back saying "Order does not have an email address.".
send_email, but include params for bothtemplate_idandemail:{"template_id": "customer_invoice", "email": "someone@example.org"}This should update the order to have a billing address. Check the mail logger and see that an Order Details email was sent.
GET wc/v3/orders/{order ID}?_embed=email_templates_embeddedproperty. Within that should be anemail_templatesitem with an array of available template IDs. This order should currently only have one available template,customer_invoice.email_templateslink, you should get back a similar array as the one in the_embeddedproperty, but each item should also include a title and description in addition to the ID.customer_invoiceandcustomer_processing_order.customer_processing_ordertemplate, but with a different email address:POST wc/v3/orders/{order ID}/actions/send_email{"template_id": "customer_processing_order", "email": "someone.else@example.org"}{"template_id": "customer_processing_order", "email": "someone.else@example.org", "force_email_update": "true"}