Webhooks

SMS Webhooks allow you to subscribe to real-time notifications about various SMS events that occur in MailerSend.

You can create a SMS webhook directly from your MailerSend account and listen for events so your integration can automatically trigger reactions.

SMS Webhooks overview

Setup

Currently, you can create a SMS webhook using the API endpoints listed below or directly from your account. Read more about webhooksopen in new window.

Available events

These are all the events you can listen to and send a notification for.

EventDescription
sms.sentFired when your SMS is sent from our sending servers. We are now waiting for a response from the receiving servers.
sms.deliveredFired when your SMS is successfully delivered with no errors.
sms.failedFired when your SMS failed to deliver.

Payload example

Our responses contain fat payloads, including the information about the event-related object, so there is no need to make an additional API request.

An example of sms.sent event:

{
  "type": "sms.sent",
  "sms_number_id": "7z3m5jgrogdpyo6n",
  "created_at": "2022-01-01T12:00:00.000000Z",
  "sms_webhook_id": "7z3m5jgrogdpyo6n",
  "url": "https://www.mailersend.com/webhook",
  "data": {
    "from": "+12345678901",
    "to": "+98765432109",
    "created_at": "2022-01-01T12:00:00.000000Z",
    "status": "sent",
    "sms_message_id": "6244233a7e194137e70e3bd2",
    "sms": {
      "id": "6244233a7e194137e70e3bd2",
      "from": "+12345678901",
      "to": "+98765432109",
      "text": "Lorem Ipsum is simply dummy text",
      "status": "sent",
      "segment_count": 1,
      "error_type": null,
      "error_description": null,
      "created_at": "2022-01-01T12:00:00.000000Z",
      "recipient": {
        "id": "6244233a7e194137e70e3bd2",
        "number": "+98765432109",
        "status": "active",
        "created_at": "2022-01-01T12:00:00.000000Z"
      }
    }
  }
}

Security

Webhook requests made by MailerSend include a Signature header. It contains a string generated by hashing the data sent to your webhook endpoint with an individual Signing Secret. A signing secret is a random string that is generated when you create a webhook.

Verifying a signature:

// $signature - a header sent by MailerSend, please refer to your framework
// or PHP manual on how to read the Signature header

// $requestContent - please refer to your framework or PHP manual on how to read the request content

$computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
return hash_equals($signature, $computedSignature);

Retrying failed webhooks

When your webhook receives a response other than a 2xx code from your endpoint URL, or if the endpoint doesn’t respond within 3 seconds, it will show up as a failed attempt in the log section of your webhook. If it receives a 2xx, then it will show as a success.

If a webhook call fails, MailerSend will retry the call a couple of times, waiting 10 seconds between the first and second attempt and 100 seconds between the second and the third attempt. This is to avoid hammering the application you want to send the information to.

Useful tools

Webhook.siteopen in new window or Pipedream.comopen in new window are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.

Get a list of SMS webhooks

If you want to retrieve information about SMS webhooks, use this GET request:

GET https://api.mailersend.com/v1/sms-webhooks

Request parameters

ParameterTypeRequiredLimitationsDetails
sms_number_idstringyes
use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$smsRecipients = $mailersend->smsWebhook->get('sms_number_id');

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.sms.webhook.list("sms_number_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import sms_webhooks

api_key = "API key here"

mailer = sms_webhooks.NewSmsWebhooks(api_key)

#Request parameters
sms_number_id = "9pq3enl6842vwrzx"

print(mailer.get_webhooks(sms_number_id))

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	options := &mailersend.ListSmsWebhookOptions{
		SmsNumberId: "sms-number-id",
	}

	_, _, err := ms.SmsWebhook.List(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sms.webhooks.SmsWebhook;
import com.mailersend.sms.webhooks.SmsWebhookList;

public void getSmsWebhooks() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        SmsWebhookList list = ms.sms().webhooks().getWebhooks("phone number id");
        
        for (SmsWebhook webhook : list.webhooks) {
            
            System.out.println(webhook.id);
        }
        
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new

# Add parameters
ms_sms_webhooks.list(sms_number_id: 'your-sms-number-id')

More examplesopen in new window

Get a single SMS webhook

To retrieve information about a single SMS webhook, use this GET request:

GET https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}

Request parameters

URL ParameterTypeRequiredLimitationsDetails
sms_webhook_idstringyes
use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$smsRecipients = $mailersend->smsWebhook->find('sms_webhook_id');

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.sms.webhook.single("sms_webhook_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import sms_webhooks

api_key = "API key here"

mailer = sms_webhooks.NewSmsWebhooks(api_key)

#Request parameters
sms_webhook_id = "aaui13enl12f2vzx"

print(mailer.get_webhook(sms_webhook_id))

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	_, _, err := ms.SmsWebhook.Get(ctx, "sms-webhook-id")
	if err != nil {
		log.Fatal(err)
	}
	
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sms.webhooks.SmsWebhook;

public void getSmsWebhook() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        SmsWebhook webhook = ms.sms().webhooks().getWebhook("webhook id");
        
        System.out.println(webhook.id);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new

# Add parameters
ms_sms_webhooks.get_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')

More examplesopen in new window

Create an SMS webhook

Create a SMS webhook using this POST request:

POST https://api.mailersend.com/v1/sms-webhooks/

Request parameters

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
urlurlyesMax: 191
namestringyesMax: 191
eventsarrayyes
enabledbooleanoptional
sms_number_idstringyesExisting hashed SMS number ID.
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsWebhookParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$smsWebhookParams = (new SmsWebhookParams())
    ->setSmsNumberId('sms_number_id')
    ->setName('Name')
    ->setUrl('https://mailersend.com/sms_webhook')
    ->setEvents(['sms.sent', 'sms.delivered', 'sms.failed'])
    ->setEnabled(false);

$smsRecipients = $mailersend->smsWebhook->create($smsWebhookParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend, SmsWebhook, SmsWebhookEventType } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const smsWebhook = new SmsWebhook()
  .setName("Sms Webhook")
  .setUrl("https:://yourapp.com/hook")
  .setSmsNumberId("sms_number_id")
  .setEnabled(true)
  .setEvents([SmsWebhookEventType.SENT, SmsWebhookEventType.DELIVERED])

mailerSend.sms.webhook.create(smsWebhook)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import sms_webhooks

api_key = "API key here"

mailer = sms_webhooks.NewSmsWebhooks(api_key)

#Request parameters
url = "https://webhook-url.com"
name = "My Webhook Name"
events = ["sms.sent"]
sms_number_id = "9pq3enl6842vwrzx"
enabled = True

print(mailer.create_webhook(url, name, events, sms_number_id, enabled))

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	events := []string{"sms.sent"}
	
	options := &mailersend.CreateSmsWebhookOptions{
		SmsNumberId: "sms-number-id",
		Name:        "Webhook",
		Events:      events,
		URL:         "https://test.com",
		Enabled:  mailersend.Bool(false),
	}
	
	_, _, err := ms.SmsWebhook.Create(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sms.webhooks.SmsWebhook;

public void createSmsWebhook() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        SmsWebhook webhook = ms.sms().webhooks().builder()
            .addEvent("sms.sent")
            .name("sms webhook")
            .url("https://example.com")
            .createWebhook("sms phone number id");
        
        System.out.print(webhook.id);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new

# Add parameters
ms_sms_webhooks.settings =
  {
    'sms_number_id' => 'your-sms-number-id',
    'name' => 'your-name',
    'url' => 'https://your-url.com',
    'events' => ['sms.sent', 'sms.delivered']
  }
puts ms_sms_webhooks.add_sms_webhook_route

More examplesopen in new window

Update a single SMS webhook

Update a SMS webhook using this PUT request:

PUT https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}

Request Parameters

URL ParameterTypeRequiredLimitationsDetails
sms_webhook_idstringyes

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
urlurloptionalMax: 191
namestringoptionalMax: 191
eventsarrayoptional
enabledbooleanoptional
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\SmsWebhookParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$smsWebhookParams = (new SmsWebhookParams())
    ->setSmsNumberId('sms_number_id')
    ->setName('Name')
    ->setUrl('https://mailersend.com/sms_webhook')
    ->setEvents(['sms.sent', 'sms.delivered', 'sms.failed'])
    ->setEnabled(false);

$smsRecipients = $mailersend->smsWebhook->update($smsWebhookParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.sms.webhook.update("sms_webhook_id", {
  name: "Webhook",
  url: "https:://yourapp.com/hook",
  enabled: ["sms.sent", "sms.delivered", "sms.failed"],
  enabled: true
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import sms_webhooks

api_key = "API key here"

mailer = sms_webhooks.NewSmsWebhooks(api_key)

#Request parameters
url = "https://different-url.com"
name = "New Webhook Name"
events = ["sms.sent", "sms.failed"],
sms_webhook_id = "aaui13enl12f2vzx"
enabled = False

print(mailer.update_webhook(sms_webhook_id, url, name, events, enabled))

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	events := []string{"sms.sent"}

	options := &mailersend.UpdateSmsWebhookOptions{
		Id:   "sms-webhook-id",
		Name: "Webhook",
		Events: events,
		Enabled: mailersend.Bool(true),
		URL:    "https://test.com",
	}
	
	_, _, err := ms.SmsWebhook.Update(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sms.webhooks.SmsWebhook;

public void updateSmsWebhook() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        SmsWebhook webhook = ms.sms().webhooks().builder()
        	.name("sms updated webhook")
        	.updateWebhook("webhook id");
        	
        System.out.print(webhook.name);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new

# Add parameters
ms_sms_webhooks.settings =
  {
    'sms_number_id' => 'your-sms-number-id',
    'name' => 'your-name',
    'url' => 'https://your-url.com',
    'events' => ['sms.sent', 'sms.delivered']
  }
puts ms_sms_webhooks.update_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')

More examplesopen in new window

Delete an SMS webhook

Delete a SMS webhook using this DELETE request:

DELETE https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}

Request Parameters

URL ParameterTypeRequiredLimitationsDetails
sms_webhook_idstringyes
import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.sms.webhook.delete("sms_webhook_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import sms_webhooks

api_key = "API key here"

mailer = sms_webhooks.NewSmsWebhooks(api_key)

#Request parameters
sms_webhook_id = "aaui13enl12f2vzx"

print(mailer.delete_webhook(sms_webhook_id))

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	_, err := ms.SmsWebhook.Delete(ctx, "sms-webhook-id")
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;

public void deleteSmsWebhook() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        boolean result = ms.sms().webhooks().deleteWebhook("webhook id");
        	
        System.out.print(result);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the SMS Webhooks class
ms_sms_webhooks = Mailersend::SMSWebhooks.new

# Add parameters
ms_sms_webhooks.delete_sms_webhook_route(sms_webhook_id: 'your-sms-webhook-id')

More examplesopen in new window

Last Updated: