Webhooks

Manage webhook endpoints

Configure webhooks to receive real-time notifications about events in your Mailtrap account. For a complete guide, see Webhooks.

List webhooks

get

Returns all webhooks for the account.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

account_idintegerRequired

Account ID

Example: 1

Responses

200

List of webhooks

application/json

401

Unauthorized. Check your API credentials.

application/json

403

Forbidden. Verify domain or check permissions.

application/json

get

/api/accounts/{account_id}/webhooks

cURL

curl -X GET https://mailtrap.io/api/accounts/{account_id}/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": 1,
      "url": "https://example.com/mailtrap/webhooks",
      "active": true,
      "webhook_type": "email_sending",
      "payload_format": "json",
      "sending_stream": "transactional",
      "domain_id": 435,
      "event_types": [
        "delivery",
        "bounce"
      ]
    },
    {
      "id": 2,
      "url": "https://example.com/mailtrap/webhooks",
      "active": true,
      "webhook_type": "audit_log",
      "payload_format": "json"
    }
  ]
}

Create a webhook

post

Create a new webhook for the account. The response includes a signing_secret that is used to verify webhook signatures.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

account_idintegerRequired

Account ID

Example: 1

Body

application/json

Responses

200

Webhook created successfully

application/json

401

Unauthorized. Check your API credentials.

application/json

403

Forbidden. Verify domain or check permissions.

application/json

422

Validation errors

application/json

post

/api/accounts/{account_id}/webhooks

cURL

curl -X POST https://mailtrap.io/api/accounts/{account_id}/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "webhook": {
      "url": "https://example.com/mailtrap/webhooks",
      "webhook_type": "email_sending",
      "payload_format": "json",
      "sending_stream": "transactional",
      "event_types": ["delivery", "bounce"],
      "domain_id": 435
    }
  }'

{
  "data": {
    "id": 1,
    "url": "https://example.com/mailtrap/webhooks",
    "active": true,
    "webhook_type": "email_sending",
    "payload_format": "json",
    "sending_stream": "transactional",
    "domain_id": 435,
    "event_types": [
      "delivery",
      "bounce"
    ],
    "signing_secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
  }
}

Get a webhook

get

Returns a single webhook by ID.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

account_idintegerRequired

Account ID

Example: 1

webhook_idintegerRequired

Webhook ID

Example: 1

Responses

200

Webhook details

application/json

401

Unauthorized. Check your API credentials.

application/json

403

Forbidden. Verify domain or check permissions.

application/json

404

Resource not found

application/json

get

/api/accounts/{account_id}/webhooks/{webhook_id}

cURL

curl -X GET https://mailtrap.io/api/accounts/{account_id}/webhooks/{webhook_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "id": 1,
    "url": "https://example.com/mailtrap/webhooks",
    "active": true,
    "webhook_type": "email_sending",
    "payload_format": "json",
    "sending_stream": "transactional",
    "domain_id": 435,
    "event_types": [
      "delivery",
      "bounce"
    ]
  }
}

Delete a webhook

delete

Permanently delete a webhook.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

account_idintegerRequired

Account ID

Example: 1

webhook_idintegerRequired

Webhook ID

Example: 1

Responses

200

Webhook deleted successfully

application/json

401

Unauthorized. Check your API credentials.

application/json

403

Forbidden. Verify domain or check permissions.

application/json

404

Resource not found

application/json

delete

/api/accounts/{account_id}/webhooks/{webhook_id}

cURL

curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/webhooks/{webhook_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "id": 1,
    "url": "https://example.com/mailtrap/webhooks",
    "active": true,
    "webhook_type": "audit_log",
    "payload_format": "json"
  }
}

Update a webhook

patch

Update an existing webhook.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

account_idintegerRequired

Account ID

Example: 1

webhook_idintegerRequired

Webhook ID

Example: 1

Body

application/json

Responses

200

Webhook updated successfully

application/json

401

Unauthorized. Check your API credentials.

application/json

403

Forbidden. Verify domain or check permissions.

application/json

404

Resource not found

application/json

422

Validation errors

application/json

patch

/api/accounts/{account_id}/webhooks/{webhook_id}

cURL

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/webhooks/{webhook_id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "webhook": {
      "active": false
    }
  }'

{
  "data": {
    "id": 1,
    "url": "https://example.com/mailtrap/webhooks",
    "active": false,
    "webhook_type": "email_sending",
    "payload_format": "json",
    "sending_stream": "transactional",
    "domain_id": 435,
    "event_types": [
      "delivery",
      "bounce",
      "unsubscribe"
    ]
  }
}