Receive email events via webhooks

Sidemail uses webhooks to notify your application when an event happens in your project. Webhooks are particularly useful for asynchronous events like when an email is delivered, bounces or when the recipient reports a spam complaint.

How to set up

• In your project's API section, add a webhook URL, and get your unique webhook secret.
• In your webhook handler, compare the value of sidemail-secret header with your webhook secret to verify the request.
• Respond to the webhook request with 200 status code (response with any other status is recognized as a webhook failure).

Node.js webhook handler example:

function handleSidemailWebhook(req, res, next) {
    // Get your webhook secret in your project's API section
    const WEBHOOK_SECRET = "wheeG1bBlmqS1TD49e4OmUOoQuN1wesyKXzKrQjN";

    // Verify that the request is coming from Sidemail
    if (req.headers["sidemail-secret"] !== WEBHOOK_SECRET) {
        return res.status(401).send();
    }

    // Your custom logic ...
    console.log(req.body.type, req.body.data);

    // Acknowledge the webhook by responding with 200 status code
    return res.status(200).send();
}

Events

Event: email.delivered

{
    "type": "email.delivered",
    "data": {
        "email": {
            "id": "123",
            "templateId": "123",
            "templateName": "Welcome",
            "templateProps": { "name": "Patrik" },
            "fromName": "Sidemail",
            "fromAddress": "hey@sidemail.io",
            "toAddress": "patrik@sidemail.io",
            "createdAt": "2020-11-07T09:50:09.951Z"
        },
        "time": "2020-11-07T09:50:09.951Z",
        "smtpResponse": "250 2.6.0 Message received"
    }
}

Event: email.bounce

{
    "type": "email.bounce",
    "data": {
        "email": {
            "id": "123",
            "templateId": "123",
            "templateName": "Welcome",
            "templateProps": { "name": "Patrik" },
            "fromName": "Sidemail",
            "fromAddress": "hey@sidemail.io",
            "toAddress": "patrik@sidemail.io",
            "createdAt": "2020-11-07T09:50:09.951Z"
        },
        "time": "2020-11-07T09:50:09.951Z",
        "bounceType": "permanent"
    }
}

Event: email.complaint

{
    "type": "email.complaint",
    "data": {
        "email": {
            "id": "123",
            "templateId": "123",
            "templateName": "Welcome",
            "templateProps": { "name": "Patrik" },
            "fromName": "Sidemail",
            "fromAddress": "hey@sidemail.io",
            "toAddress": "patrik@sidemail.io",
            "createdAt": "2020-11-07T09:50:09.951Z"
        },
        "time": "2020-11-07T09:50:09.951Z",
        "complaintFeedbackType": "abuse"
    }
}