From e4694bdb5f92c41949545c3c87ff58bd2a98c573 Mon Sep 17 00:00:00 2001 From: Leonid Shevtsov Date: Fri, 26 Jun 2026 11:29:00 +0300 Subject: [PATCH] MT-22654: document tracking opt-outs public API Decisions: - Mirror suppressions path style (`/api/tracking_opt_outs`) for account-scoped v2 endpoints - SDK samples deferred until client libraries ship tracking opt-out support Co-authored-by: Cursor --- specs/email-sending.openapi.yml | 215 +++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 2 deletions(-) diff --git a/specs/email-sending.openapi.yml b/specs/email-sending.openapi.yml index 4db5f13..6a5eadb 100644 --- a/specs/email-sending.openapi.yml +++ b/specs/email-sending.openapi.yml @@ -3,7 +3,7 @@ info: title: Email Sending version: 2.0.0 description: | - Manage domains, suppressions, and email sending logs for your Mailtrap account. + Manage domains, suppressions, tracking opt-outs, and email sending logs for your Mailtrap account. contact: name: Mailtrap Support url: 'https://docs.mailtrap.io' @@ -16,7 +16,7 @@ info: servers: - description: | - Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs. + Mailtrap account API (`mailtrap.io`) for domains, suppressions, tracking opt-outs, stats, and email logs. Error JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array). url: 'https://mailtrap.io' @@ -37,6 +37,12 @@ tags: description: | Control which email addresses should not receive emails from your account. + - name: tracking-opt-outs + x-page-title: Tracking Opt-Outs + x-page-description: Manage tracking opt-outs + description: | + Manage email addresses that have opted out of open and click tracking. + - name: stats x-page-title: Stats x-page-description: Email sending stats @@ -571,6 +577,7 @@ paths: "domain": { "open_tracking_enabled": true, "click_tracking_enabled": true, + "tracking_opt_out_enabled": true, "auto_unsubscribe_link_enabled": false } }' @@ -591,6 +598,7 @@ paths: domain: open_tracking_enabled: true click_tracking_enabled: true + tracking_opt_out_enabled: true auto_unsubscribe_link_enabled: false responses: '200': @@ -1291,6 +1299,145 @@ paths: '404': $ref: '#/components/responses/NotFound' + /api/tracking_opt_outs: + get: + summary: List tracking opt-outs + description: | + List email addresses that have opted out of open and click tracking. Returns up to 1000 records per request. Use `last_id` for cursor-based pagination through large lists. + + Rate limit: 10 requests per minute per account. + operationId: getTrackingOptOuts + tags: + - tracking-opt-outs + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + # Get all tracking opt-outs + curl -X GET https://mailtrap.io/api/tracking_opt_outs \ + -H 'Authorization: Bearer YOUR_API_KEY' + + # Search for specific email + curl -X GET 'https://mailtrap.io/api/tracking_opt_outs?email=tracked@example.com' \ + -H 'Authorization: Bearer YOUR_API_KEY' + parameters: + - name: email + in: query + description: Filter tracking opt-outs by exact email address (case-insensitive). + schema: + type: string + format: email + example: tracked@example.com + - name: start_time + in: query + description: Filter tracking opt-outs created at or after this timestamp (ISO 8601 format). + schema: + type: string + format: date-time + example: '2025-01-01T00:00:00Z' + - name: end_time + in: query + description: Filter tracking opt-outs created at or before this timestamp (ISO 8601 format). + schema: + type: string + format: date-time + example: '2025-12-31T23:59:59Z' + - name: last_id + in: query + description: The tracking opt-out UUID from the last record of the previous response. Returns records after this opt-out, enabling cursor-based pagination through large lists. + schema: + type: string + format: uuid + example: 64d71bf3-1276-417b-86e1-8e66f138acfe + responses: + '200': + $ref: '#/components/responses/GetTrackingOptOutsResponse' + '400': + $ref: '#/components/responses/BAD_REQUEST' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/LIMIT_EXCEEDED' + post: + summary: Create tracking opt-out + description: | + Add an email address to the tracking opt-out list. Opted-out addresses are excluded from open and click tracking. + + {% hint style="warning" %} + This endpoint requires admin-level access. + {% endhint %} + + Rate limit: 10 requests per minute per account. + operationId: createTrackingOptOut + tags: + - tracking-opt-outs + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + curl -X POST https://mailtrap.io/api/tracking_opt_outs \ + -H 'Authorization: Bearer YOUR_API_KEY' \ + -H 'Content-Type: application/json' \ + -d '{ + "email": "tracked@example.com" + }' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [email] + properties: + email: + type: string + format: email + description: Email address to opt out of tracking + example: tracked@example.com + responses: + '201': + $ref: '#/components/responses/CreateTrackingOptOutResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '429': + $ref: '#/components/responses/LIMIT_EXCEEDED' + + /api/tracking_opt_outs/{tracking_opt_out_id}: + delete: + summary: Delete tracking opt-out + description: | + Remove an email address from the tracking opt-out list so open and click tracking can apply again. + + {% hint style="warning" %} + This endpoint requires admin-level access. + {% endhint %} + operationId: deleteTrackingOptOut + tags: + - tracking-opt-outs + x-codeSamples: + - lang: shell + label: 'cURL' + source: | + curl -X DELETE https://mailtrap.io/api/tracking_opt_outs/{tracking_opt_out_id} \ + -H 'Authorization: Bearer YOUR_API_KEY' + parameters: + - $ref: '#/components/parameters/tracking_opt_out_id' + responses: + '200': + $ref: '#/components/responses/DeleteTrackingOptOutResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '/api/stats': get: operationId: getAccountSendingStats @@ -2034,6 +2181,16 @@ components: format: uuid example: 64d71bf3-1276-417b-86e1-8e66f138acfe + tracking_opt_out_id: + name: tracking_opt_out_id + in: path + required: true + description: The tracking opt-out UUID + schema: + type: string + format: uuid + example: 64d71bf3-1276-417b-86e1-8e66f138acfe + sending_message_id: name: sending_message_id in: path @@ -2219,6 +2376,11 @@ components: type: boolean click_tracking_enabled: type: boolean + tracking_opt_out_enabled: + type: boolean + description: | + When enabled, recipients can opt out of open and click tracking via a link in tracked emails. + Requires open or click tracking to be enabled. auto_unsubscribe_link_enabled: type: boolean custom_domain_tracking_enabled: @@ -2286,6 +2448,7 @@ components: name: mt-link open_tracking_enabled: true click_tracking_enabled: true + tracking_opt_out_enabled: false auto_unsubscribe_link_enabled: true custom_domain_tracking_enabled: true health_alerts_enabled: true @@ -2305,6 +2468,11 @@ components: click_tracking_enabled: type: boolean description: Enable click tracking for links in emails sent from this domain + tracking_opt_out_enabled: + type: boolean + description: | + Enable the tracking opt-out link in tracked emails sent from this domain. + Requires open or click tracking to be enabled. auto_unsubscribe_link_enabled: type: boolean description: Automatically add an unsubscribe link to emails sent from this domain @@ -2537,6 +2705,23 @@ components: message_subject: type: [string, 'null'] + TrackingOptOut: + type: object + properties: + id: + type: string + format: uuid + description: The tracking opt-out UUID + example: 64d71bf3-1276-417b-86e1-8e66f138acfe + email: + type: string + format: email + example: tracked@example.com + created_at: + type: string + format: date-time + example: '2025-01-15T10:30:00Z' + Webhook: type: object properties: @@ -3605,3 +3790,29 @@ components: properties: data: $ref: '#/components/schemas/Suppression' + + GetTrackingOptOutsResponse: + description: List of tracking opt-outs + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TrackingOptOut' + + DeleteTrackingOptOutResponse: + description: Tracking opt-out deleted + content: + application/json: + schema: + $ref: '#/components/schemas/TrackingOptOut' + + CreateTrackingOptOutResponse: + description: Tracking opt-out created + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/TrackingOptOut'