diff --git a/specs/email-sending.openapi.yml b/specs/email-sending.openapi.yml index a9d7c7d..3a56d33 100644 --- a/specs/email-sending.openapi.yml +++ b/specs/email-sending.openapi.yml @@ -45,6 +45,13 @@ tags: x-page-description: Email logs description: List and retrieve email sending logs for the account. + - name: webhooks + x-page-title: Webhooks + x-page-description: Manage webhook endpoints + description: | + Configure webhooks to receive real-time notifications about events in + your Mailtrap account. For a complete guide, see + [Webhooks](https://docs.mailtrap.io/email-api-smtp/advanced/webhooks). paths: /api/accounts/{account_id}/sending_domains: post: @@ -1358,6 +1365,370 @@ paths: '429': $ref: '#/components/responses/LIMIT_EXCEEDED' + /api/accounts/{account_id}/webhooks: + post: + operationId: createWebhook + summary: Create a webhook + description: | + Create a new webhook for the account. The response includes a + `signing_secret` that is used to [verify webhook signatures](https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#webhook-signature-verification). + tags: + - webhooks + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + 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 + } + }' + parameters: + - $ref: '#/components/parameters/account_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - webhook + properties: + webhook: + type: object + required: + - url + - webhook_type + properties: + url: + type: string + format: uri + description: The URL that will receive webhook payloads. + example: 'https://example.com/mailtrap/webhooks' + webhook_type: + type: string + description: | + The type of webhook. Determines which events the webhook can subscribe to. + enum: + - email_sending + - campaigns + - audit_log + example: email_sending + active: + type: boolean + description: Whether the webhook is active. Defaults to `true`. + default: true + example: true + payload_format: + type: string + description: Format of the webhook payload. + enum: + - json + - jsonlines + default: json + example: json + sending_stream: + type: string + description: | + Sending stream the webhook subscribes to. Required for `email_sending` webhook type. + enum: + - transactional + - bulk + example: transactional + event_types: + type: array + description: | + List of event types to subscribe to. Required for `email_sending` and `campaigns` webhook types. + items: + type: string + enum: + - delivery + - soft_bounce + - bounce + - suspension + - unsubscribe + - open + - spam_complaint + - click + - reject + example: + - delivery + - bounce + domain_id: + type: integer + description: | + Scopes the webhook to a specific domain ID, or all + domains if omitted. Applicable only for `email_sending` + and `campaigns` webhooks. + example: 435 + responses: + '200': + description: Webhook created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookCreateResponse' + example: + 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 + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableEntity' + + get: + operationId: listWebhooks + summary: List webhooks + description: Returns all webhooks for the account. + tags: + - webhooks + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + curl -X GET https://mailtrap.io/api/accounts/{account_id}/webhooks \ + -H 'Authorization: Bearer YOUR_API_KEY' + parameters: + - $ref: '#/components/parameters/account_id' + responses: + '200': + description: List of webhooks + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Webhook' + example: + 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 + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + + /api/accounts/{account_id}/webhooks/{webhook_id}: + get: + operationId: getWebhook + summary: Get a webhook + description: Returns a single webhook by ID. + tags: + - webhooks + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + curl -X GET https://mailtrap.io/api/accounts/{account_id}/webhooks/{webhook_id} \ + -H 'Authorization: Bearer YOUR_API_KEY' + parameters: + - $ref: '#/components/parameters/account_id' + - $ref: '#/components/parameters/webhook_id' + responses: + '200': + description: Webhook details + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Webhook' + example: + 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 + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + + patch: + operationId: updateWebhook + summary: Update a webhook + description: | + Update an existing webhook. + tags: + - webhooks + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + 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 + } + }' + parameters: + - $ref: '#/components/parameters/account_id' + - $ref: '#/components/parameters/webhook_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - webhook + properties: + webhook: + type: object + properties: + url: + type: string + format: uri + description: The URL that will receive webhook payloads. + example: 'https://example.com/mailtrap/webhooks' + active: + type: boolean + description: Whether the webhook is active. + example: false + payload_format: + type: string + description: Format of the webhook payload. + enum: + - json + - jsonlines + example: json + event_types: + type: array + description: List of event types to subscribe to. Applicable only for `email_sending` and `campaigns` webhooks. + items: + type: string + enum: + - delivery + - soft_bounce + - bounce + - suspension + - unsubscribe + - open + - spam_complaint + - click + - reject + example: + - delivery + - bounce + - unsubscribe + responses: + '200': + description: Webhook updated successfully + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Webhook' + example: + 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 + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + + delete: + operationId: deleteWebhook + summary: Delete a webhook + description: Permanently delete a webhook. + tags: + - webhooks + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/webhooks/{webhook_id} \ + -H 'Authorization: Bearer YOUR_API_KEY' + parameters: + - $ref: '#/components/parameters/account_id' + - $ref: '#/components/parameters/webhook_id' + responses: + '200': + description: Webhook deleted successfully + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Webhook' + example: + data: + id: 1 + url: 'https://example.com/mailtrap/webhooks' + active: true + webhook_type: audit_log + payload_format: json + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + components: securitySchemes: HeaderAuth: @@ -1408,6 +1779,15 @@ components: type: string format: uuid + webhook_id: + name: webhook_id + in: path + required: true + description: Webhook ID + schema: + type: integer + example: 1 + StartDateQueryFilter: name: start_date description: Start date for which to include the results. @@ -1672,6 +2052,88 @@ components: type: string format: date-time + Webhook: + type: object + properties: + id: + type: integer + example: 1 + url: + type: string + format: uri + example: 'https://example.com/mailtrap/webhooks' + active: + type: boolean + example: true + webhook_type: + type: string + enum: + - email_sending + - campaigns + - audit_log + example: email_sending + payload_format: + type: string + enum: + - json + - jsonlines + example: json + sending_stream: + type: + - string + - 'null' + enum: + - transactional + - bulk + - null + description: | + Sending stream the webhook is subscribed to. Applicable only for + `email_sending` webhooks. + example: transactional + domain_id: + type: + - integer + - 'null' + description: | + Scopes the webhook to a specific domain ID, or all domains if + omitted. Applicable only for `email_sending` and `campaigns` + webhooks. + example: 435 + event_types: + type: array + description: | + List of event types the webhook is subscribed to. Applicable only + for `email_sending` and `campaigns` webhooks. + items: + type: string + enum: + - delivery + - soft_bounce + - bounce + - suspension + - unsubscribe + - open + - spam_complaint + - click + - reject + example: + - delivery + - bounce + + WebhookCreateResponse: + type: object + properties: + data: + allOf: + - $ref: '#/components/schemas/Webhook' + - type: object + properties: + signing_secret: + type: string + description: | + Secret key for verifying webhook payload signatures using HMAC SHA-256. Only returned on creation. + example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 + UnprocessableEntity: type: object properties: