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 webhooks.

Available events

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

Event	Description
sms.sent	Fired when your SMS is sent from our sending servers. We are now waiting for a response from the receiving servers.
sms.delivered	Fired when your SMS is successfully delivered with no errors.
sms.failed	Fired 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.site or Pipedream.com 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

Parameter	Type	Required	Limitations	Details
sms_number_id	string	yes

use MailerSend\MailerSend;

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

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

More examples

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 examples

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 examples

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 examples

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 examples

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 examples

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 Parameter	Type	Required	Limitations	Details
sms_webhook_id	string	yes

use MailerSend\MailerSend;

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

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

More examples

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 examples

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 examples

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 examples

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 examples

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 examples

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 Parameter	Type	Required	Limitations	Details
url	url	yes	Max: 191
name	string	yes	Max: 191
events	array	yes
enabled	boolean	optional
sms_number_id	string	yes		Existing 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 examples

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 examples

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 examples

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 examples

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 examples

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 examples

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 Parameter	Type	Required	Limitations	Details
sms_webhook_id	string	yes

JSON parameters are provided in dot notation

JSON Parameter	Type	Required	Limitations	Details
url	url	optional	Max: 191
name	string	optional	Max: 191
events	array	optional
enabled	boolean	optional

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 examples

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 examples

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 examples

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 examples

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 examples

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 examples

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 Parameter	Type	Required	Limitations	Details
sms_webhook_id	string	yes

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 examples

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 examples

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 examples

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 examples

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 examples