Tracking Opt-Outs

Manage tracking opt-outs

Manage email addresses that have opted out of open and click tracking. Tracking opt-outs are always scoped to a sending domain.

List tracking opt-outs

get

List email addresses that have opted out of open and click tracking for your sending domains. Each record includes the domain it applies to.

Returns up to 1000 records per request. When the response includes a non-null last_id, pass it as the last_id query parameter to fetch the next page.

Rate limit: 10 requests per minute per account.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Query parameters

emailstring · emailOptional

Filter tracking opt-outs by exact email address (case-insensitive).

Example: [e-mail]

start_timestring · date-timeOptional

Filter tracking opt-outs created at or after this timestamp (ISO 8601 format).

Example: 2025-01-01T00:00:00Z

end_timestring · date-timeOptional

Filter tracking opt-outs created at or before this timestamp (ISO 8601 format).

Example: 2025-12-31T23:59:59Z

last_idstring · uuidOptional

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.

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe

Responses

200

List of tracking opt-outs

application/json

last_idstring · nullableOptional

Cursor for the next page. Present when the response is a full page (1000 records); pass this value as the last_id query parameter to continue. null when there are no more pages.

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe

400

Bad request - invalid parameters.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

429

Rate limit exceeded for the current account.

application/json

get/api/tracking_opt_outs

cURL

# 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=[e-mail]' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
      "email": "[e-mail]",
      "created_at": "2025-01-15T10:30:00Z",
      "domain_name": "example.com"
    }
  ],
  "last_id": "64d71bf3-1276-417b-86e1-8e66f138acfe"
}

Create tracking opt-out

post

Add an email address to the tracking opt-out list for a sending domain. Opted-out addresses are excluded from open and click tracking on that domain.

This endpoint requires admin-level access.

Rate limit: 10 requests per minute per account.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Body

application/json

emailstring · emailRequired

Email address to opt out of tracking

Example: [e-mail]

domain_idintegerRequired

ID of the sending domain this tracking opt-out applies to

Example: 12345

Responses

201

Tracking opt-out created

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Validation errors

application/json

429

Rate limit exceeded for the current account.

application/json

post/api/tracking_opt_outs

cURL

curl -X POST https://mailtrap.io/api/tracking_opt_outs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[e-mail]",
    "domain_id": 12345
  }'

{
  "data": {
    "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
    "email": "[e-mail]",
    "created_at": "2025-01-15T10:30:00Z",
    "domain_name": "example.com"
  }
}

Delete tracking opt-out

delete

Remove an email address from the tracking opt-out list so open and click tracking can apply again.

This endpoint requires admin-level access.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

tracking_opt_out_idstring · uuidRequired

The tracking opt-out UUID

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe

Responses

200

Tracking opt-out deleted

application/json

idstring · uuidOptional

The tracking opt-out UUID

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe

emailstring · emailOptionalExample: [e-mail]

created_atstring · date-timeOptionalExample: 2025-01-15T10:30:00Z

domain_namestringOptional

Sending domain this tracking opt-out applies to

Example: example.com

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

delete/api/tracking_opt_outs/{tracking_opt_out_id}

cURL

curl -X DELETE https://mailtrap.io/api/tracking_opt_outs/{tracking_opt_out_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
  "email": "[e-mail]",
  "created_at": "2025-01-15T10:30:00Z",
  "domain_name": "example.com"
}