Create Webhook

curl --request POST \
  --url https://app.lettr.com/api/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Order Notifications",
  "url": "https://example.com/webhook",
  "auth_type": "basic",
  "auth_username": "user",
  "auth_password": "secret",
  "events_mode": "selected",
  "events": [
    "message.delivery",
    "message.bounce"
  ]
}
'

import requests

url = "https://app.lettr.com/api/webhooks"

payload = {
    "name": "Order Notifications",
    "url": "https://example.com/webhook",
    "auth_type": "basic",
    "auth_username": "user",
    "auth_password": "secret",
    "events_mode": "selected",
    "events": ["message.delivery", "message.bounce"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Order Notifications',
    url: 'https://example.com/webhook',
    auth_type: 'basic',
    auth_username: 'user',
    auth_password: 'secret',
    events_mode: 'selected',
    events: ['message.delivery', 'message.bounce']
  })
};

fetch('https://app.lettr.com/api/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.lettr.com/api/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Order Notifications',
    'url' => 'https://example.com/webhook',
    'auth_type' => 'basic',
    'auth_username' => 'user',
    'auth_password' => 'secret',
    'events_mode' => 'selected',
    'events' => [
        'message.delivery',
        'message.bounce'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.lettr.com/api/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.lettr.com/api/webhooks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.lettr.com/api/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Webhook created successfully.",
  "data": {
    "id": "webhook-abc123",
    "name": "Order Notifications",
    "url": "https://example.com/webhook",
    "enabled": true,
    "event_types": [
      "message.delivery",
      "message.bounce"
    ],
    "auth_type": "basic",
    "has_auth_credentials": true,
    "last_successful_at": null,
    "last_failure_at": null,
    "last_status": null
  }
}

POST

webhooks

Create Webhook

curl --request POST \
  --url https://app.lettr.com/api/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Order Notifications",
  "url": "https://example.com/webhook",
  "auth_type": "basic",
  "auth_username": "user",
  "auth_password": "secret",
  "events_mode": "selected",
  "events": [
    "message.delivery",
    "message.bounce"
  ]
}
'

import requests

url = "https://app.lettr.com/api/webhooks"

payload = {
    "name": "Order Notifications",
    "url": "https://example.com/webhook",
    "auth_type": "basic",
    "auth_username": "user",
    "auth_password": "secret",
    "events_mode": "selected",
    "events": ["message.delivery", "message.bounce"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Order Notifications',
    url: 'https://example.com/webhook',
    auth_type: 'basic',
    auth_username: 'user',
    auth_password: 'secret',
    events_mode: 'selected',
    events: ['message.delivery', 'message.bounce']
  })
};

fetch('https://app.lettr.com/api/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.lettr.com/api/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Order Notifications',
    'url' => 'https://example.com/webhook',
    'auth_type' => 'basic',
    'auth_username' => 'user',
    'auth_password' => 'secret',
    'events_mode' => 'selected',
    'events' => [
        'message.delivery',
        'message.bounce'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.lettr.com/api/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.lettr.com/api/webhooks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.lettr.com/api/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Order Notifications\",\n  \"url\": \"https://example.com/webhook\",\n  \"auth_type\": \"basic\",\n  \"auth_username\": \"user\",\n  \"auth_password\": \"secret\",\n  \"events_mode\": \"selected\",\n  \"events\": [\n    \"message.delivery\",\n    \"message.bounce\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Webhook created successfully.",
  "data": {
    "id": "webhook-abc123",
    "name": "Order Notifications",
    "url": "https://example.com/webhook",
    "enabled": true,
    "event_types": [
      "message.delivery",
      "message.bounce"
    ],
    "auth_type": "basic",
    "has_auth_credentials": true,
    "last_successful_at": null,
    "last_failure_at": null,
    "last_status": null
  }
}

Authorizations

Authorization

string

header

required

API key for authentication

Body

application/json

Request body for creating a webhook

name

string

required

Name of the webhook

Maximum string length: 255

Example:

"Order Notifications"

url

string<uri>

required

URL where webhook events will be sent

Maximum string length: 2048

Example:

"https://example.com/webhook"

auth_type

enum<string>

required

Authentication type for the webhook

Available options:

none,

basic,

oauth2

Example:

"basic"

events_mode

enum<string>

required

Whether to receive all events or only selected ones

Available options:

all,

selected

Example:

"selected"

auth_username

string

Username for basic authentication (required when auth_type is 'basic')

Maximum string length: 255

Example:

"user"

auth_password

string

Password for basic authentication (required when auth_type is 'basic')

Maximum string length: 255

Example:

"secret"

oauth_client_id

string

OAuth2 client ID (required when auth_type is 'oauth2')

Maximum string length: 255

oauth_client_secret

string

OAuth2 client secret (required when auth_type is 'oauth2')

Maximum string length: 255

oauth_token_url

string<uri>

OAuth2 token URL (required when auth_type is 'oauth2')

Maximum string length: 2048

events

enum<string>[]

List of event types to receive (required when events_mode is 'selected'). Fully-prefixed names such as message.delivery are canonical; short names (delivery) and the legacy engagament.* prefix are accepted for backwards compatibility and are normalised to the fully-prefixed form.

Available options:

message.injection,

message.delivery,

message.bounce,

message.delay,

message.out_of_band,

message.spam_complaint,

message.policy_rejection,

engagement.click,

engagement.open,

engagement.initial_open,

engagement.amp_click,

engagement.amp_open,

engagement.amp_initial_open,

generation.generation_failure,

generation.generation_rejection,

unsubscribe.list_unsubscribe,

unsubscribe.link_unsubscribe,

relay.relay_injection,

relay.relay_rejection,

relay.relay_delivery,

relay.relay_tempfail,

relay.relay_permfail

Example:

["message.delivery", "message.bounce"]

Response

Webhook created successfully

Response after creating a webhook

message

string

required

Human-readable response message

Example:

"Webhook created successfully."

data

object

required

View of a webhook

Show child attributes

List Webhooks Get Webhook

API Reference

Emails

Scheduled Emails

Domains

Templates

Webhooks

System

Campaigns

Audience Lists

Audience Contacts

Audience Topics

Audience Properties

Audience Segments

Create Webhook

Authorizations

Body

Response