Skip to content
Kirim.Email SMTP API

Create a new webhook

POST
/api/domains/{domain}/webhooks
curl --request POST \
  --url https://smtp-app.kirim.email/api/domains/example.com/webhooks \
  --header 'Content-Type: application/json' \
  --data '{ "type": "queued", "url": "https://example.com/webhook" }'

Create a new webhook configuration for the specified domain owned by the authenticated user

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
domain
required
string
Example
example.com

Domain name that must be owned by the authenticated user

Request Bodyrequired

Section titled “Request Bodyrequired”

Webhook configuration details

Media typeapplication/json
object
type
required

Event type that will trigger this webhook

string
Allowed values: queued send delivered bounced failed permanent_fail opened clicked unsubscribed temporary_fail deferred
Example
delivered
url
required

URL endpoint where webhook events will be sent (must use HTTP or HTTPS)

string format: uri
Example
https://example.com/webhook

Responses

Section titled “Responses”

201

Section titled “201”

Webhook created successfully

Media typeapplication/json
object
success

Indicates the request was successful

boolean
message

Human-readable success message

string
data

Webhook configuration for email event notifications

object
webhook_guid

Unique identifier for the webhook

string format: uuid
user_guid

GUID of the user who owns the webhook

string
user_domain_guid

GUID of the domain associated with the webhook

string
user_smtp_guid

GUID of the SMTP configuration

string
type

Event type that triggers the webhook

string
Allowed values: queued send delivered bounced failed permanent_fail opened clicked unsubscribed temporary_fail deferred
url

URL endpoint where webhook events will be sent

string format: uri
is_deleted

Whether the webhook has been deleted

boolean
created_at

Unix timestamp when the webhook was created

integer
modified_at

Unix timestamp when the webhook was last modified

integer
Example
{
  "success": true,
  "message": "Webhook created successfully.",
  "data": {
    "webhook_guid": "550e8400-e29b-41d4-a716-446655440000",
    "user_guid": "user-guid-123",
    "user_domain_guid": "domain-guid-456",
    "user_smtp_guid": "smtp-guid-789",
    "type": "queued",
    "url": "https://example.com/webhook",
    "is_deleted": false,
    "created_at": 1640995200,
    "modified_at": 1640995200
  }
}

401

Section titled “401”

Unauthorized - Invalid or missing authentication credentials

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Unauthorized"
}

404

Section titled “404”

Not Found - Domain or webhook not found

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Domain not found or you do not own this domain"
}

422

Section titled “422”

Validation Error - Invalid input data

Media typeapplication/json
object
success
boolean
message
string
errors

Field-specific validation errors

object
Example
{
  "success": false,
  "message": "Validation failed."
}

429

Section titled “429”

Too Many Requests - Rate limit exceeded. Retry after the specified time.

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Too many attempts. Please try again later."
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds until rate limit resets

X-RateLimit-Limit
integer

Maximum requests per minute

X-RateLimit-Remaining
integer

Remaining requests in current window

500

Section titled “500”

Server Error - Unexpected error occurred

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "An error occurred while processing the request."
}