Programmatically send email when shipping tracking number is set

Question

I am looking for a way to programmatically send an email to the user when a tracking number is assigned to an order. I need to be able to do this programmatically because I am using an outside source to populate the tracking information.

I guess what I am really looking for here is a specific trigger or event that I could use to fire off the email that would normally be sent when the admin clicks the "Send Tracking Information" button. I have skimmed through the core code and have not been able to put my finger on what action is actually being triggered when that button is pushed.

We are using a third party (eBridge) to connect with our sales tools. Once an order has been marked as shipped and a tracking number is input into the eBridge tool, it will talk to magento and input the tracking number into the order. The problem is that it doesn't tell magento to fire off an email to provide the customer with this newly inputted tracking number. What I am trying to do is, once the information is put into magento fire off an email from magentos side. Is this possible? What we want, in a nutshell, is to be able to have magento send off an email with the tracking information without having to manually go into each order and click the "Send Tracking Information" button.

Answer 1

When you add a new shipment to an order via the control panel you can tick a box to send the e-mail. If you need to send this programmatically, the controller for the admin area simply calls the sendEmail method on the Mage_Sales_Model_Order_Shipment.

UPDATE: If the tracking number is being adding to the shipment via the 'standard' method, which is to say the addTrack method of the shipment api, then you would be able to hook into the sales_order_shipment_track_save_after event. Adding an observer that does something along the lines of...

public function sendTrackEmail($observer)
{
    $track = $observer->getEvent()->getTrack();
    $shipment = $track->getShipment(true);
    $shipment->sendEmail();
}

Answer 2

FYI there is an undocumented API call that does exactly this, sendInfo(). I don't know as of what version this was added in, as far as I can tell it's over a year old, I just had to solve this same problem myself and this is one of the first results on Google.

Note: If you're implementing this, you likely do not want to send the email flag to the sales_order_shipment.create() API call, as this will result in two emails going out for the same order, one without a tracking number, then one with it.

addTrack() is likely implemented already, you just need to follow it immediately with sendInfo().

sales_order_shipment.addTrack(sessionId, shipmentIncrementId, carrier, title, trackNumber)
sales_order_shipment.sendInfo(sessionId, comment)

The email sent out is the same that you would get by clicking the "Send Tracking Information" button in the Magento backend manually. Reference the Magento API for more explanation on addTrack and using the SOAP API in general.

As for sendInfo() specifically, take a look at the source code from magento/app/code/core/Mage/Sales/Model/Order/Shipment/Api.php for help:

/**
 * Send email with shipment data to customer
 *
 * @param string $shipmentIncrementId
 * @param string $comment
 * @return bool
 */
public function sendInfo($shipmentIncrementId, $comment = '')
{
    /* @var $shipment Mage_Sales_Model_Order_Shipment */
    $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);

    if (!$shipment->getId()) {
        $this->_fault('not_exists');
    }

    try {
        $shipment->sendEmail(true, $comment)
            ->setEmailSent(true)
            ->save();
        $historyItem = Mage::getResourceModel('sales/order_status_history_collection')
            ->getUnnotifiedForInstance($shipment, Mage_Sales_Model_Order_Shipment::HISTORY_ENTITY_NAME);
        if ($historyItem) {
            $historyItem->setIsCustomerNotified(1);
            $historyItem->save();
        }
    } catch (Mage_Core_Exception $e) {
        $this->_fault('data_invalid', $e->getMessage());
    }

    return true;
}