API Tokens

List API tokens

get

Returns all API tokens visible to the current API token.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

Responses

200

List of API tokens

application/json

idinteger · int64Optional

API token ID

namestringOptional

Token display name

last_4_digitsstringOptional

Last 4 characters of the token (full token is only shown on create or reset)

created_bystringOptional

Name of the user or token that created this token

expires_atstring · date-time · nullableOptional

When the token expires (ISO 8601); null if the token does not expire

401

Returns unauthorized error message. Check your credentials.

application/json

get

/api/accounts/{account_id}/api_tokens

cURL

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

[
  {
    "id": 12345,
    "name": "My API Token",
    "last_4_digits": "x7k9",
    "created_by": "[email protected]",
    "expires_at": null,
    "resources": [
      {
        "resource_type": "account",
        "resource_id": 3229,
        "access_level": 100
      }
    ]
  }
]

Create API token

post

Creates a new API token for the account with the given name and resource permissions.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

Body

application/json

namestringRequired

Display name for the token

Responses

200

Created API token (includes full token value once)

application/json

idinteger · int64Optional

API token ID

namestringOptional

Token display name

last_4_digitsstringOptional

Last 4 characters of the token (full token is only shown on create or reset)

created_bystringOptional

Name of the user or token that created this token

expires_atstring · date-time · nullableOptional

When the token expires (ISO 8601); null if the token does not expire

tokenstringOptional

Full token value (only returned on create or reset; store securely)

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Validation error or other business rule violation

application/json

post

/api/accounts/{account_id}/api_tokens

cURL

curl -X POST https://mailtrap.io/api/accounts/{account_id}/api_tokens \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My API Token",
    "resources": [
      {"resource_type": "account", "resource_id": 3229, "access_level": 100}
    ]
  }'

{
  "id": 12345,
  "name": "My API Token",
  "last_4_digits": "x7k9",
  "created_by": "[email protected]",
  "expires_at": null,
  "resources": [
    {
      "resource_type": "account",
      "resource_id": 3229,
      "access_level": 100
    }
  ],
  "token": "a1b2c3d4e5f6..."
}

Get API token

get

Returns a single API token by id.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

idinteger · int64Required

API token ID

Example: 12345

Responses

200

API token

application/json

idinteger · int64Optional

API token ID

namestringOptional

Token display name

last_4_digitsstringOptional

Last 4 characters of the token (full token is only shown on create or reset)

created_bystringOptional

Name of the user or token that created this token

expires_atstring · date-time · nullableOptional

When the token expires (ISO 8601); null if the token does not expire

401

Returns unauthorized error message. Check your credentials.

application/json

404

Returns not found error message

application/json

get

/api/accounts/{account_id}/api_tokens/{id}

cURL

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

{
  "id": 12345,
  "name": "My API Token",
  "last_4_digits": "x7k9",
  "created_by": "[email protected]",
  "expires_at": null,
  "resources": [
    {
      "resource_type": "account",
      "resource_id": 3229,
      "access_level": 100
    }
  ]
}

Delete API token

delete

Permanently deletes an API token.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

idinteger · int64Required

API token ID

Example: 12345

Responses

204

Token deleted (no body)

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

delete

/api/accounts/{account_id}/api_tokens/{id}

cURL

curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/api_tokens/{id} \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

No content

Reset API token

post

Expires the requested token and creates a new token with the same permissions. The old token stops working after a short grace period. The response includes the new token value (store it securely; it is only returned once). Only tokens that have not already been reset (no expiration set) can be reset.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

idinteger · int64Required

API token ID

Example: 12345

Responses

200

New API token (includes full token value once)

application/json

idinteger · int64Optional

API token ID

namestringOptional

Token display name

last_4_digitsstringOptional

Last 4 characters of the token (full token is only shown on create or reset)

created_bystringOptional

Name of the user or token that created this token

expires_atstring · date-time · nullableOptional

When the token expires (ISO 8601); null if the token does not expire

tokenstringOptional

Full token value (only returned on create or reset; store securely)

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

422

Validation error or other business rule violation

application/json

post

/api/accounts/{account_id}/api_tokens/{id}/reset

cURL

curl -X POST https://mailtrap.io/api/accounts/{account_id}/api_tokens/{id}/reset \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

{
  "id": 12345,
  "name": "My API Token",
  "last_4_digits": "x7k9",
  "created_by": "[email protected]",
  "expires_at": null,
  "resources": [
    {
      "resource_type": "account",
      "resource_id": 3229,
      "access_level": 100
    }
  ],
  "token": "a1b2c3d4e5f6..."
}