There are several events in the Group Commerce system which trigger emails, and they are broken up into two classes of emails: Orders and Profiles.
When configured in Pub Admin, our system will POST callbacks to URLs you specify with the information necessary to render and send email content.
Your endpoints should respond with the exact content "OK" (without
quotes) on success; anything else for a failure (we use the string
In the event of a failure, our system will retry the request sometime later.
|The event for which this email should be sent.
See below for the types
|A JSON object which will provide all of the information that you could
not otherwise retrieve. e.g., an OrderId, but not a fully-baked Order object.
(Subsequent API requests will be needed to gather remaining data.)
See below for the JSON formats, based on the emailType
||A secret key shared between our systems.
This will determine the culture into which the email should be rendered.
- Profile Related
- welcome - Sent on Profile creation
- forgotpassword - Sent when a user initiates the reset password process
- Order Related
- canceled - Sent when an order is cancelled
- chargedfailed - Sent when an attempt to process a charge fails (as opposed to failed authorization)
- fulfilled - Sent when an order or partial order has been
fulfilled. In the event that an order is fulfilled in parts, this email
will be sent more than once. Included in the request is the list of
order detail itemkeys which have been fulfilled.
- placed - Sent when an order is placed
- raoaward - Sent when a user has earned a free offer through referrals
- raopurchase - Sent to a referring user that one of their referred users has purchased, making them one referral closer to a free item.
- rafaward - Sent when a user has earned credit toward future purchases through referrals
- voucherReminder - Sent when a voucher is due to expire
JSON data which will contain all of the necessary order or profile data needed to render this email.
See below for more details on the format of dataJson determined by the emailType above.
Defined in Pub Admin, use this key to authenticate the request.
Some things to consider:
- The timeout on this call is 90 seconds.
- In most cases, you will need to make further API requests to gather
more detailed information used to render an email. For example, Order
email requests contain an orderId, so a call to the GetOrderById API endpoint will be required to gather details about that order.
- We use the URLs /callback/order and /callback/profile in our implementations.
- We make the necessary API calls to gather data and render our email templates
- We use the API's sendEmail endpoint to actually send the content
- We then use the sendEmailResponse success property to determine what to send in the callback response.
More thorough implementations might
include a message queue such that your site can accept the email
callback requests, respond immediately, and render/send the email with a
background process. This would lighten the load on your web servers
and virtually eliminate the callback timeout concerns.
dataJson Objects (with sample data):
"userKey": "key representing the user"
Reset Password (email)
"userKey": "key representing the user",
"resetToken": "reset token" // see: Reset Password
Order Cancelled (order)
", ...], // see: Order Detail itemKey
"reason": 0 // 0: Customer Service (CS) Cancelled; 1: Credit Card
Failed; 2: CS Refund; 3: CS Void; 4: Auto Refund Unfulfilled Order
Charge Failed (order)
Order Fulfilled (order)
"orderDetailItemKeys": ["key", ...], // see: Order Detail itemKey
Order Placed (order)
Refer an Offer Award (order)
Refer an Offer Purchase (order)
Refer a Friend Award (order)
"userKeyToGetNotification": "user key",
Voucher Reminder (order)