Welcome‎ > ‎Version 3‎ > ‎Publisher Api‎ > ‎Building Your Own Site‎ > ‎

Emails/Email Callbacks

Emails/Email Callbacks
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 "FAIL").
In the event of a failure, our system will retry the request sometime later.


Field Data Type Nulls Description
cultureCode string
Culture Code
emailType string

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
sharedKey string
  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.
Use the API's GetPublisher call and compare the response object's emailNotificationCallbackSharedKey to this sharedKey.

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.

Our implementation:
  1. We use the URLs /callback/order and /callback/profile in our implementations.
  2. We make the necessary API calls to gather data and render our email templates
  3. We use the API's sendEmail endpoint to actually send the content
  4. 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):

Welcome (email)
"userKey": "key representing the user"

Reset Password (email)
    "userKey": "key representing the user",
    "resetToken": "reset token" // see: Reset Password

Order Cancelled (order)
    "orderId": 12345,
    "orderDetailItemKeys": ["
key", ...], // 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)
    "orderId": 12345

Order Fulfilled (order)
    "orderId": 12345,
    "orderDetailItemKeys": ["key", ...], // see: Order Detail itemKey
    "giftNotification": false

Order Placed (order)
    "orderId": 12345

Refer an Offer Award (order)
    "orderId": 12345,
    "offerOptionId": 23456

Refer an Offer Purchase (order)
    "orderId": 12345,
    "offerOptionId": 23456,
    "howManyNeeded": 3,
    "howManyPurchased": 1

Refer a Friend Award (order)
    "userKeyToGetNotification": "user key",
    "orderIdThatTriggered": 12345

Voucher Reminder (order)
    "orderId": 12345,
    "itemKey": "key" // see: Order Detail itemKey