Email

Table of Content:

Create email

This API endpoint creates an unverified email and sends a verification code.

Endpoint: https://apis.threatwinds.com/api/auth/v2/email

Parameters

Parameter Location Type Required Description Example
Authorization header string Yes Bearer token from an active session.  
address body string Yes The email parameter represents a user’s email address that’s going to be associated with their account. This email address is used for communication with the user and may also be used as a way to reset their password or verify their account. “john@doe.com”

To create an email, use a POST request, for example:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/auth/v2/email' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "john@doe.com"
}'

Returns

HTTP 202:

{
  "verificationCodeID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e"
}

A verification code is sent to the email address. Use Verify email to complete the process.

Note: Verification codes expire after 5 minutes. A maximum of 3 attempts are allowed per code before it is invalidated. If the code expires or attempts are exhausted, create a new email to receive a fresh code.

Delete email

This API endpoint deletes an email from the authenticated user’s account. You cannot delete a PREFERRED email — set another email as PREFERRED first.

Endpoint: https://apis.threatwinds.com/api/auth/v2/email/:id

Parameters

Parameter Location Type Required Description Example
Authorization header string Yes This authorization header can be obtained from an active session of the account.  
id path uuid Yes The id of the email that you want to delete. 5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e

To delete an email, use a DELETE request, for example:

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/auth/v2/email/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json'

Returns

HTTP 202 with an acknowledgement body:

{
  "message": "acknowledged"
}

Get emails

This API endpoint gets the user’s emails.

Endpoint: https://apis.threatwinds.com/api/auth/v2/emails

Parameters

Parameter Location Type Required Description  
Authorization header string Yes Bearer token from an active session.  

To get the current emails, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/auth/v2/emails' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

HTTP 200:

{
  "emails": [
    {
      "id": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "emailID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "address": "john@doe.net",
      "verified": true,
      "preferred": true
    },
    {
      "id": "6a2b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
      "emailID": "6a2b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
      "address": "john+alt@doe.net",
      "verified": false,
      "preferred": false
    }
  ]
}

Note: The emailID field is deprecated. Use id instead. emailID is kept for backward compatibility and will be removed in a future release.

Note: Results are silently limited to 10 emails maximum. There is no pagination support for this endpoint.

404 if the user has no emails.

Verify email

This API endpoint verifies the email using code sent by email.

Endpoint: https://apis.threatwinds.com/api/auth/v2/email/verification

Parameters

Parameter Location Type Required Description Example
verificationCodeID body uuid Yes You can get it from the email that you wish to verify at the time of its creation. “1c233e4a-27e7-4b77-8b0d-9a35cf212afe”
code body string Yes This code is sent to your email when it is created. “757564”

Note: This endpoint does not require authentication. Only the verification code and ID are needed.

To verify an email, use a PUT request, for example:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/auth/v2/email/verification' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "757564",
  "verificationCodeID": "1c233e4a-27e7-4b77-8b0d-9a35cf212afe"
}'

Returns

HTTP 202 with an acknowledgement body:

{
  "message": "acknowledged"
}

Set email as preferred

This API endpoint sets an email as preferred

Endpoint: https://apis.threatwinds.com/api/auth/v2/email/preferred

Parameters

Parameter Location Type Required Description Example
Authorization header string Yes This authorization header can be obtained from an active session of the account.  
emailID body uuid Yes The id of the email that you’d like to set as preferred. 5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e

To set a preferred email, use a PUT request, for example:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/auth/v2/email/preferred' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "emailID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e"
}'

Returns

A successful response returns a JSON object with a success message:

{
  "message": "acknowledged"
}

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header Description
x-error Human-readable error message describing what went wrong
x-error-id Unique identifier for error tracking and support

Error Codes

Status Code Description Possible Cause
400 Bad Request Invalid request parameters or malformed JSON
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Authenticated user lacks permission for this operation
404 Not Found The requested resource does not exist
500 Internal Server Error Server-side error; please contact support if persistent