openapi: 3.1.0 info: version: 2.0.0-oas3 title: TurboSMTP Public APIs license: name: MIT url: https://opensource.org/licenses/MIT description: > This document describes all public turboSMTP **V2** API and offers endpoints Descriptions, Parameters, Requests, Responses and Samples of usage. [Click here to view the previous version of turboSMTP Public API Version 1.0](https://www.serversmtp.com/turbo-api-1) # Useful Links for Developers - [Email SDKs for Developers](https://serversmtp.com/email-sdks-for-developers) - [Webhooks Reference](https://serversmtp.com/event-webhook-reference/) - [Email API for Developers](https://serversmtp.com/email-api-for-developers) # Security For the most part (and where not otherwise explicit) turboSMTP's API requires authorization. Both methods are passed as HTTP request headers. ## Base URLs Different endpoints live on different hosts: | Host | Used for | |---|---| | `https://pro.api.serversmtp.com/api/v2` | All endpoints **except** `/mail/send` | | `https://api.turbo-smtp.com/api/v2` | `POST /mail/send` only | | `https://api.eu.turbo-smtp.com/api/v2` | `POST /mail/send` only — EU sending infrastructure | ## Authentication Methods | Method | Headers | Lifetime | Best for | |---|---|---|---| | **API Key** | `Authorization: ` | 2 hours (or non-expiring with `no_expire: true`) | Interactive sessions, account administration | | **Consumer Key / Secret** | `consumerKey: ` + `consumerSecret: ` | Permanent until deleted | Production integrations, sending email | **Endpoint-specific rules:** - **`POST /mail/send` accepts only `consumerKey`/`consumerSecret`** — requests with an `Authorization` header will be rejected with `401`. - **Consumer key management (`/user/consumerKeys`) requires the `Authorization` header** — you cannot create or delete consumer keys while authenticated with a consumer key. - **The `Authorization` value is the raw key** — do not prefix it with `Bearer` or any other scheme. ## * API Key Issued by `POST /authorize` upon a successful email + password challenge. Returned as the `auth` field. With `no_expire: false` (default) the key expires after **2 hours**; set `no_expire: true` for a non-expiring key. To revoke a key call `POST /deauthorize`. > `/authorize` is rate-limited — cache and reuse the key rather than calling it before every request. (Use [/authorize](#/authentication/AuthenticationLogin) to obtain an API Key) ## * Consumer Key / Secret A permanent key/secret pair tied to your account (not to your password). Consumer keys support IP-based restrictions and can be revoked individually — they are the recommended method for production and are **required** for `/mail/send`. > The `consumerSecret` is returned **only at creation time** and cannot be retrieved later — store it securely. (Use [/user/consumerKeys](#/consumerkey/createConsumerKey) to create a Consumer Key / Secret pair) # Data Interchange Format For the most part (and where not otherwise explicit) turboSMTP’s API uses JSON as the data format of choice when it comes to request and response bodies. contact: email: api@turbo-smtp.com servers: - url: https://pro.api.serversmtp.com/api/v2 description: turboSMTP API — all endpoints except /mail/send tags: - name: mail description: Send email message - name: authentication description: Authentication - name: suppressions description: Suppressions - name: meta description: Meta - name: billing description: Billing - name: email-validator description: Email Validator - name: subaccounts description: Subaccounts - name: alerts description: Alerts - name: analytics description: Analytics - name: consumerkey description: Api Keys paths: /authorize: post: security: [] tags: - authentication summary: Login - Get API Key operationId: AuthenticationLogin description: > **This endpoint allows you to get an API Key** By providing your turboSMTP authentication details you will be able to get an API Key. Use your API Key to consume APIs that require authorization. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AuthenticationLoginRequestBody" responses: "200": description: > Sucess User logged in sucessfully, use the auth value as API Key from request body in future API calls. content: application/json: schema: $ref: "#/components/schemas/AuthenticationLoginSucessResponsetBody" "400": description: | Bad Request ###### Produces: * missing_required_parameter content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "403": description: | Forbidden Email address or password provided are incorrect. ###### Produces: * wrong_credentials_specified content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: wrong_credentials_specified /deauthorize: post: tags: - authentication summary: Logout - Revoke API Key security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: AuthenticationLogout description: | **This endpoint allows you to revoke your API Key** responses: "200": description: | Sucess User logged out sucessfully, API Key is no longer valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: token_deauthorized "401": $ref: "#/components/responses/Unauthorized" /change-password: put: tags: - authentication summary: Change turboSMTP password security: - ApiKeyAuth: [] operationId: ChangePassword description: > **This endpoint allows you to change your current password** Note: Only ApiKeyAuth is supported. ConsumerKey/ConsumerSecret authentication will return 403. ## PASSWORD RULES * Passwords must have at least 10 characters. * At least one character must be uppercase. * At least one character must be lowercase. * At least one character must be numeric. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChangePasswordRequestBody" responses: "200": description: | Sucess Password changed sucessfully. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * invalid_mail_address * current_password_is_missing * current_password_can_not_be_empty * password_is_missing * password_length_should_not_be_less_than_10_characters * password_should_contain_at_least_one_uppercase_character * password_should_contain_at_least_one_lowercase_character * password_should_contain_at_least_one_digit * confirm_password_is_missing * password_should_equal_confirm_password * new_password_should_not_equal_current_password content: application/json: schema: $ref: "#/components/schemas/ChangePasswordBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": description: | Forbidden Current password provided is incorrect. ###### Produces: * password_is_invalid * not_allowed_for_apikey content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: password_is_invalid /forgot-password: post: security: [] tags: - authentication summary: Forgot Password - Use in case you don´t remember your turboSMTP password operationId: SendSecretTokenResetPassword description: > **This endpoint will allow you to get an email that will help you reset your turboSMTP password** In your password reset email you will find: * A **Reset Password** button that will take you to the password reset form on turboSMTP website. * A secret token to be used to reset the password via [/authentication/forgot-password](#/authentication/updateResetPassword). **Note**: Token is vaid for 1 hour. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SendSecretTokenResetPasswordRequestBody" responses: "200": description: > Success Password reset email sent if the address is registered. Always returns success to prevent email enumeration. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * empty_request_body * missing_required_parameter content: application/json: schema: $ref: "#/components/schemas/SendSecretTokenResetPasswordBadRequestResponseBody" get: tags: - authentication summary: Forgot Password - Verify if Secret Passord Recovery token is valid. security: - ApiKeyAuth: [] operationId: CheckValidityTokenResetPassword parameters: - name: token in: query description: Secret Token required: true schema: type: string description: | Forgot Password - check if secret token is valid **Note**: Tokens are valid for 1 hour. responses: "200": description: | Sucess Token is valid. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * forgot_password_token_is_missing content: application/json: schema: $ref: "#/components/schemas/CheckValidityTokenResetPasswordBadRequestResponseBo\ dy" "403": description: | Forbidden Token is invalid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: token_is_invalid put: security: [] tags: - authentication summary: Forgot Password - change password operationId: UpdateResetPassword description: > **This endpoint allows you to reset your password by using a password reset token** ## PASSWORD RULES * Passwords must have at least 10 characters. * At least one character must be uppercase. * At least one character must be lowercase. * At least one character must be numeric. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateResetPasswordRequestBody" responses: "200": description: | Sucess Password reset sucessfully. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * empty_request_body * token_is_missing * token_can_not_be_empty * password_is_missing * password_length_should_not_be_less_than_10_characters * password_should_contain_at_least_one_uppercase_character * password_should_contain_at_least_one_lowercase_character * password_should_contain_at_least_one_digit * confirm_password_is_missing * password_should_equal_confirm_password content: application/json: schema: $ref: "#/components/schemas/UpdateResetPasswordBadRequestResponseBody" "403": description: | Forbidden Token is invalid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: token_is_invalid /mail/send: post: servers: - url: https://api.turbo-smtp.com/api/v2 description: Send infrastructure — global - url: https://api.eu.turbo-smtp.com/api/v2 description: Send infrastructure — EU tags: - mail summary: Send email message security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: sendEmail description: > Send email message ###### Servers | Host | Region | |---|---| | `https://api.turbo-smtp.com/api/v2` | Global (default) | | `https://api.eu.turbo-smtp.com/api/v2` | European infrastructure — use for EU data residency | ###### **Notes:** **- ConsumerKey / ConsumerSecret headers should be used. This endpoint does not support Authorization header** **- Switch between samples to learn about advanced features such as using attachments, custom headers like reply-to address, tracking, embeded images and others.** ###### Limitations: * The total size of your email, including attachments, must be less than 24MB. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Email-2" examples: Short: summary: Simple Email Send Request Body value: from: FROM NAME to: user@example.com,user2@example.com subject: This is a test message cc: cc_user@example.com bcc: bcc_user@example.com content: This is plain text version of the message. html_content: This is HTML version of the message. Full: summary: Complete Email Send Request Body value: from: user@example.com to: user@example.com,user2@example.com subject: This is a test message cc: cc_user@example.com bcc: bcc_user@example.com content: This is plain text version of the message. html_content: This is HTML version of the message. custom_headers: List-Unsubscribe: X-Entity-Ref-ID: 4ec7b020-51dc-442f-bd39-9b0a32c3eb83 Tracking-Id: "888884433" reply-to: alternative-email@domain.com mime_raw: string reference_id: 333fe3e9-05aa-4ead-85cf-de625b0222c6 X-campaign-ID: AB Test attachments: - content: dXBsb2FkZXIxQGdtYWlsLmNvbQ0KdXBsb2FkZXIyQGdtYWlsLmNvbQ0KYWJjMQ== name: list.txt type: text/plain Images: summary: Email with Embedded Images using CID value: from: user@example.com to: test@example.com subject: This is a Message subject html_content:

attachments: - content_id: content: data:image/jpeg;base64,/BASE_64_OF_THE_IMAGE name: image.jpg type: image/jpeg responses: "200": description: | Sucess Turbo-SMTP successfully received your message. content: application/json: schema: $ref: "#/components/schemas/SendSucessResponsetBody" "400": description: > Bad Request There was a problem processing the request due to an invalid/missing parameter for the request. content: application/json: schema: $ref: "#/components/schemas/SendBadRequestResponseBody" examples: MissingSender: summary: Sender mail address (from) has not been issued or is invalid value: message: error errors: - missing or not valid sender email (from) MissingRecipients: summary: Recipients mail addresses (to) have not been issued value: message: error errors: - missing recipients (to) InvalidRecipients: summary: Invalid email addresses in to, cc or bcc fields value: message: error errors: - "'abc' 'to' email not valid" - "'cc_@ab1' 'cc' email not valid" - "'bcc_@ab3' 'bcc' email not valid" InvalidMime: summary: Invalid MIME content value: message: error errors: - Invalid Mime InsuficientCredit: summary: Not enought credit in account subscription value: message: error errors: - nocredit "401": description: | Unauthorized Missing or Invalid Turbo-SMTP credentials provided. content: application/json: schema: $ref: "#/components/schemas/SendUnauthorizedResponseBody" examples: MissingAuthorizationToken: summary: Authorization tokens are not present. value: errorCode: 3 message: Invalid authorization token details: "No authorization key was specified for request: POST /api/mail/send" InvalidAuthorizationToken: summary: Authorization Tokens are invalid. value: errorCode: 3 message: Wrong credentials specified DeactivatedAccount: summary: Account is innactive value: errorCode: 3 message: Account for developer@your-domain.com is inactive /suppressions/import: post: operationId: importSuppressions tags: - suppressions summary: Import Suppressions security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Import Suppressions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SuppressionImportJson" multipart/form-data: schema: $ref: "#/components/schemas/SuppressionImportFile" responses: "200": description: | Sucess Email Addresses were imported. content: application/json: schema: $ref: "#/components/schemas/SuppressionUploadResponse" links: CleanupByBulkDelete: operationId: bulkDeleteSuppressions requestBody: $response.body#/valid "400": description: | Bad Request ###### Produces: * missing_upload_file * invalid_mail_address_list content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /suppressions: get: tags: - suppressions summary: Get Suppressions Data security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: getSuppressions description: | Get Suppressions Data parameters: - $ref: "#/components/parameters/PageQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/FromQueryParam" - $ref: "#/components/parameters/ToQueryParam" - $ref: "#/components/parameters/TimezoneQueryParam" - $ref: "#/components/parameters/SuppressionFilterQueryParam" - $ref: "#/components/parameters/SuppressionFilterByQueryParam" - $ref: "#/components/parameters/SmartSearchQueryParam" - $ref: "#/components/parameters/SuppressionOrderByQueryParam" - $ref: "#/components/parameters/OrderTypeQueryParam" responses: "200": description: | Sucess Get Filtered Suppressions Data. content: application/json: schema: $ref: "#/components/schemas/SuppressionsSucessResponsetBody" "401": $ref: "#/components/responses/Unauthorized" post: tags: - suppressions summary: Filter suppressions security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: filterSuppressions description: | Get Suppressions Data requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SuppressionFilterOrderPageRequestBody" responses: "200": description: | Sucess Get Filtered Suppressions Data. content: application/json: schema: $ref: "#/components/schemas/SuppressionsSucessResponsetBody" "401": $ref: "#/components/responses/Unauthorized" /suppressions/csv: get: tags: - suppressions summary: Export Suppressions data in CSV file security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: exportSuppressionsDataCSV description: | Export Suppressions data in CSV file parameters: - $ref: "#/components/parameters/FromQueryParam" - $ref: "#/components/parameters/ToQueryParam" - $ref: "#/components/parameters/TimezoneQueryParam" - $ref: "#/components/parameters/SuppressionFilterQueryParam" - $ref: "#/components/parameters/SuppressionFilterByQueryParam" - $ref: "#/components/parameters/SmartSearchQueryParam" - $ref: "#/components/parameters/SuppressionOrderByQueryParam" - $ref: "#/components/parameters/OrderTypeQueryParam" responses: "200": $ref: "#/components/responses/SuppressionsCSV" "401": $ref: "#/components/responses/Unauthorized" post: tags: - suppressions summary: Export filtered suppressions security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: exportFilterSuppressions description: | Export Filtered Suppressions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SuppressionFilterRequestBody" responses: "200": $ref: "#/components/responses/SuppressionsCSV" "401": $ref: "#/components/responses/Unauthorized" /suppressions/bulk_delete: post: security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] tags: - suppressions summary: Bulk delete suppressions operationId: bulkDeleteSuppressions description: | Bulk delete suppressions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SuppressionBulkDeleteRequestBody" responses: "200": description: Suppressions were sucessfully deleted. content: application/json: schema: $ref: "#/components/schemas/SuppressionsDeleteSuccess" "400": description: | Bad Request ###### Produces: * no_contacts_were_provided content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /suppressions/delete: post: tags: - suppressions summary: Delete suppressions security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: deleteFilterSuppressions description: | Delete suppressions requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SuppressionFilterRequestBody" responses: "200": description: deleted content: application/json: schema: $ref: "#/components/schemas/SuppressionsDeleteSuccess" "400": description: | Bad Request ###### Produces: * content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /meta/countries: get: tags: - meta summary: Get countries security: [] operationId: getCountries description: | Get countries (public endpoint, no authentication required) responses: "200": description: Countries list content: application/json: schema: $ref: "#/components/schemas/CountryList" "/meta/state/{isoCode}": get: tags: - meta summary: Get states by country security: [] operationId: getStatesByCountry description: | Get states by country (public endpoint, no authentication required) parameters: - $ref: "#/components/parameters/IsoCodePathParam" responses: "200": description: States selected content: application/json: schema: $ref: "#/components/schemas/StateList" "404": description: | Not Found Please verify the Country Iso Code Provided. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: invalid_iso_code /billing/buy_emailvalidation_credits: post: security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] tags: - billing summary: Buy Email Validator Credits operationId: buyEmailValidatorCredits description: | Buy Email Validator Credits requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BuyEmailValidatorCreditsRequest" responses: "200": description: | Sucess Returns url to the billing system to allow payment completition. content: application/json: schema: $ref: "#/components/schemas/BuyEmailValidatorCreditsSucessResponse" "400": description: | Bad Request ###### Produces: * missing_required_parameter_amount * amount_should_be_integer * amount_should_not_be_less_than_15 * amount_should_not_be_higher_than_1800 * can_not_buy_extra_credit_without_active_plan content: application/json: schema: $ref: "#/components/schemas/BuyEmailValidatorCreditsBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /emailvalidation/subscription: get: operationId: getEmailValidationSubscription tags: - email-validator summary: Get Email Validation subscription security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: > This endpoint allows to get details about remaining credit / balance for email validation. responses: "200": description: > Sucess Email Validation Subscription. #### Note: #### * Free credits are measured in credits units, each credit enables 1 email validation. * Paid credits represent available monetary balance, as email vaidations are performed, balance will be deduced, cost per email validation is variable depending on ammount of validated emails. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorSubscription" "401": $ref: "#/components/responses/Unauthorized" /emailvalidation/upload: post: operationId: uploadEmailValidationFile tags: - email-validator summary: Upload file for email validation security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Upload file for email validation requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: | CSV or TXT file containing email addresses (one per line). Supported formats: text/csv (CSV), text/plain (TXT). The file may contain invalid email addresses; these will be processed and flagged as invalid in the validation results. responses: "201": description: | Sucess Uploaded file was created at the server. content: application/json: schema: $ref: "#/components/schemas/EmailValidationUploadResponse" links: GetListById: operationId: getEmailValidationListSummary parameters: Id: $response.body#/list_id ValidateListById: operationId: validateEmailValidatorList parameters: Id: $response.body#/list_id DeleteListById: operationId: deleteEmailValidationListById parameters: Id: $response.body#/list_id "400": description: | Bad Request ###### Produces: * missing_upload_file * invalid_mail_address_list * unsupported_file_format content: application/json: schema: $ref: "#/components/schemas/EmailValidatorUploadBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /emailvalidation/lists: get: operationId: getEmailValidationLists tags: - email-validator summary: Get Email validation lists information security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | List files for email validation information parameters: - $ref: "#/components/parameters/PageQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/FromQueryParam" - $ref: "#/components/parameters/ToQueryParam" - $ref: "#/components/parameters/TimezoneQueryParam" responses: "200": description: | Sucess Get Email Validation Lists Data. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorSucessResponsetBody" "401": $ref: "#/components/responses/Unauthorized" "/emailvalidation/lists/{Id}": get: operationId: getEmailValidationListSummary tags: - email-validator summary: Get Email validation list details security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get Email validation list details parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Get Email Validation List Data. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorList" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: list_not_found delete: operationId: deleteEmailValidationListById tags: - email-validator summary: Delete email validation list security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Delete email validation list parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Email validation list was deleted. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorListDeleteSuccess" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: list_not_found "/emailvalidation/lists/{Id}/validate": post: operationId: validateEmailValidatorList tags: - email-validator summary: | Validate list in Email Validator security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Validate list in Email Validator parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess List was validated sucessfully. "400": description: | Bad Request ###### Produces: * list_already_validated * insufficient_credit content: application/json: schema: $ref: "#/components/schemas/EmailValidatorValidateListBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: list_not_found "/emailvalidation/lists/{Id}/emails": get: operationId: getValidatedEmailsByList tags: - email-validator summary: Get Validated Emails by Email Validation List security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get Validated Emails by Email Validation List parameters: - $ref: "#/components/parameters/PageQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Get Email Validation List Data. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorValidatedMailsResults" examples: ValidatedList: summary: Example for a list that has been validated value: count: 2 processed: 2 results: - email: mail@thearter-gallery.eu id: 500157 status: do_not_mail sub_status: "" free_email: false domain: thearter-gallery.eu domain_age_days: null smtp_provider: null mx_found: true mx_record: gmail-smtp-in.l.google.com - email: staffdevelopment@guidingteachers.org id: 500158 status: valid sub_status: "" free_email: false domain: guidingteachers.org domain_age_days: null smtp_provider: null mx_found: true mx_record: gmail-smtp-in.l.google.com NotValidatedList: summary: Example for a list that has not been validated yet value: count: 2 processed: 0 results: [] "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: list_not_found "/emailvalidation/lists/{Id}/emails/{emailId}": get: operationId: getEmailValidationDataByEmailId tags: - email-validator summary: Get Email validation data by email ID. security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get Email validation data by email ID. parameters: - $ref: "#/components/parameters/IdParam" - name: emailId in: path required: true schema: type: integer description: Email validation ID obtained from the list. responses: "200": description: > Sucess Details of validated email address. **Note**: Make sure to check the complete "status" and "sub_status" properties documentation from the schema. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorListEmailDetails" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id and email id are valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" examples: InvalidListId: summary: Invalid List Id value: message: list_not_found InvalidEmailId: summary: Invalid Email Id value: message: email_not_found "/emailvalidation/lists/{Id}/csv": get: operationId: exportCSVValidatedEmailsByList tags: - email-validator summary: Export Validated Emails by Email Validation List to CSV File security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Export Validated Emails by Email Validation List to CSV File parameters: - $ref: "#/components/parameters/IdParam" responses: "200": $ref: "#/components/responses/ValidatedEmailsCSV" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the list id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: list_not_found /emailvalidation/validateEmail: post: operationId: validateEmail tags: - email-validator summary: Validate single email address security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Validate singleemail adddress. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EmailAddressRequestBody" responses: "200": description: > Sucess Details of validated email address. **Note**: Make sure to check the complete "status" and "sub_status" properties documentation from the schema. content: application/json: schema: $ref: "#/components/schemas/EmailValidatorMailDetails" "400": description: | Bad Request ###### Produces: * invalid_email_address * missing_required_parameter_email content: application/json: schema: $ref: "#/components/schemas/EmailValidatorValidateBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /subaccounts/list: get: operationId: getSubaccounts tags: - subaccounts summary: Get Subaccounts lists information security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | List subaccounts information parameters: - $ref: "#/components/parameters/PageQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/SubaccountFilterByEmailQueryParam" - $ref: "#/components/parameters/SubaccountFilterByActiveQueryParam" - $ref: "#/components/parameters/SubaccountFilterByIPQueryParam" - $ref: "#/components/parameters/SubaccountOrderByQueryParam" - $ref: "#/components/parameters/OrderTypeQueryParam" responses: "200": description: | Sucess Subaccounts list. content: application/json: schema: $ref: "#/components/schemas/SubAccountListSucessResponsetBody" "400": description: | Bad Request ###### Produces: * page_should_be_integer * page_should_be_greater_than_0 * limit_should_be_integer * limit_should_be_greater_than_0 * filter_by_active_should_be_boolean * ip_should_be_IPV4_format * order_by_can_only_be_email_or_last_used * ordertype_should_be_asc_or_desc "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": description: | Not Found Page not found. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: page_not_found /subaccounts/email-exists: get: operationId: checkIfAccountEmailExists tags: - subaccounts summary: Check if account email exists in turboSMTP security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Check if account email exists in turboSMTP parameters: - $ref: "#/components/parameters/EmailQueryParam" responses: "200": description: > Sucess Returns true if email address is already associated to a turboSMTP account. content: application/json: schema: $ref: "#/components/schemas/CommmonResultResponseBody" "400": description: | Bad Request ###### Produces: * missing_required_parameter_email content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" /subaccounts: post: operationId: createSubaccount tags: - subaccounts summary: Create Subaccount. security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Create subaccount. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SubaccountCreateRequest" responses: "201": description: Sub account details. content: application/json: schema: $ref: "#/components/schemas/Subaccount" "400": description: | Bad Request ###### Produces: * email_is_already_in_use * missing_required_parameter_email * missing_required_parameter_first_name * missing_required_parameter_last_name * missing_required_parameter_password * password_length_should_not_be_less_than_10_characters * password_should_contain_at_least_one_uppercase_character * password_should_contain_at_least_one_digit * missing_required_parameter_confirm_password * password_should_equal_confirm_password * missing_required_parameter_ip * ip_should_be_IPV4_format * ip_not_associated_to_user_account * policy_agree_should_be_true content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "/subaccounts/{Id}": get: operationId: getSubaccountDetails tags: - subaccounts summary: Get sub account details security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get sub account details. parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: Sub account details. content: application/json: schema: $ref: "#/components/schemas/Subaccount" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": $ref: "#/components/responses/SubaccountNotFound" patch: operationId: updateSubaccountDetails tags: - subaccounts summary: Update sub account details security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Update sub account details. parameters: - $ref: "#/components/parameters/IdParam" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SubaccountUpdateRequest" responses: "200": description: Sub account updated sucessfully. content: application/json: schema: $ref: "#/components/schemas/Subaccount" "400": description: | Bad Request ###### Produces: * password_length_should_not_be_less_than_10_characters * password_should_contain_at_least_one_uppercase_character * password_should_contain_at_least_one_digit * password_should_equal_confirm_password * ip_should_be_IPV4_format * ip_not_associated_to_user_account * policy_agree_should_be_true content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": $ref: "#/components/responses/SubaccountNotFound" "/subaccounts/{Id}/updatesubaccountsmtplimit": post: operationId: UpdateSubaccountSMTPLimit tags: - subaccounts summary: Set subaccount smtp limit security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Set subaccount smtp limit. parameters: - $ref: "#/components/parameters/IdParam" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SubaccountSMTPLimit" responses: "200": description: Subaccount smtp limit set sucessfully content: application/json: schema: $ref: "#/components/schemas/SubaccountActivePlan" "400": description: | Bad Request ###### Produces: * missing_required_parameter_limit * limit_should_be_integer * limit_should_not_be_higher_than_parent_account_limit * limit_should_not_be_lower_than_-1 content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": $ref: "#/components/responses/SubaccountNotFound" "/subaccounts/{Id}/updatesubaccountstatus": post: operationId: UpdateSubaccountStatus tags: - subaccounts summary: Set subaccount status security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Set subaccount status. parameters: - $ref: "#/components/parameters/IdParam" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SubaccountActiveStatus" responses: "200": description: Subaccount status set sucessfully content: application/json: schema: $ref: "#/components/schemas/SubaccountActivePlan" "400": description: | Bad Request ###### Produces: * missing_required_parameter_active * active_should_be_boolean content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": $ref: "#/components/responses/SubaccountNotFound" /subaccounts/authorize: post: operationId: SubaccountAuthenticationLogin tags: - subaccounts summary: Login to a subaccount security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Login to a subaccount. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Email" responses: "200": description: > Sucess User logged in sucessfully, use the auth value as API Key from request body in future API calls. content: application/json: schema: $ref: "#/components/schemas/AuthenticationLoginSucessResponsetBody" "400": description: | Bad Request ###### Produces: * missing_required_parameter_email content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "403": description: | Forbidden Email address or password provided are incorrect. ###### Produces: * wrong_credentials_specified * feature_not_available_for_active_plan content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: wrong_credentials_specified "/subaccounts/{Id}/active-plan": get: operationId: getActivePlan tags: - subaccounts summary: Get subaccount active plan. security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get subaccount active plan. parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: Login successfull content: application/json: schema: $ref: "#/components/schemas/SubaccountActivePlan" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/ForbiddenForActivePlan" "404": $ref: "#/components/responses/SubaccountNotFound" /subaccounts/logo: post: operationId: uploadLogoFile tags: - subaccounts summary: Upload agency logo security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Upload agency logo. Logo must be a png or jpeg image. requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary responses: "200": description: | Sucess The Logo file was successfully submitted. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * missing_upload_file * file_type_should_be_png_or_jpeg content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" get: operationId: getLogoFile tags: - subaccounts summary: Get agency logo security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get agency logo responses: "200": $ref: "#/components/responses/LogoSuccess" "401": $ref: "#/components/responses/Unauthorized" delete: operationId: deleteLogoFile tags: - subaccounts summary: Delete agency logo security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Delete agency logo responses: "200": description: | Sucess Logo was deleted. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Agency Logo was not found. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: logo_not_found /subaccounts/agency: get: operationId: getAgencySettings tags: - subaccounts summary: Update Agency details security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get Agency details. responses: "200": description: Agency details. content: application/json: schema: $ref: "#/components/schemas/AgencySettings" "401": $ref: "#/components/responses/Unauthorized" patch: operationId: updateAgencySettings tags: - subaccounts summary: Update Agency details security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Update Agency Details requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BaseAgencySettings" responses: "200": description: | Sucess Agency details updated sucessfully content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "400": description: | Bad Request ###### Produces: * agency_name_should_be_shorter_than_128_characters * agency_website_should_be_shorter_than_128_characters * agency_footer_should_be_shorter_than_2048_characters content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" /tools/alerts: get: operationId: getAlerts tags: - alerts summary: Get Alerts Notifications Information security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | List Alerts Notifications Information responses: "200": description: | Sucess Alerts list. content: application/json: schema: $ref: "#/components/schemas/AlertListSucessResponsetBody" "401": $ref: "#/components/responses/Unauthorized" post: operationId: createAlert tags: - alerts summary: Create new Alert Notification security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Create new Alert Notification requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AlertBase" example: email: alert@example.com percentage: 80 responses: "201": description: | Sucess Alert Notification Created Sucessfully. content: application/json: schema: $ref: "#/components/schemas/Alert" links: GetAlertById: operationId: getAlert parameters: Id: $response.body#/id UpdateAlertById: operationId: updateAlert parameters: Id: $response.body#/id DeleteAlertById: operationId: deleteAlert parameters: Id: $response.body#/id "400": description: | Bad Request ###### Produces: * missing_required_parameter_email * missing_required_parameter_percentage * percentage_should_be_integer * percentage_should_not_be_less_than_0 * percentage_should_not_be_higher_than_100 content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "/tools/alerts/{Id}": patch: operationId: updateAlert tags: - alerts summary: Update Alert Notification security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Update Alert Notification. parameters: - $ref: "#/components/parameters/IdParam" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AlertBase" example: email: alert@example.com percentage: 80 responses: "200": description: | Sucess Alert updated sucessfully. content: application/json: schema: $ref: "#/components/schemas/Alert" "400": description: | Bad Request ###### Produces: * percentage_should_be_integer * percentage_should_not_be_less_than_0 * percentage_should_not_be_higher_than_100 content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the alert id exists. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: alert_not_found get: operationId: getAlert tags: - alerts summary: Get Alert Notification security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Get Alert Notification. parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Alert Notification. content: application/json: schema: $ref: "#/components/schemas/Alert" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the alert id exists. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: alert_not_found delete: operationId: deleteAlert tags: - alerts summary: Delete Alert Notification security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] description: | Delete an Alert Notification. parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Alert was deleted. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the alert id exists. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: alert_not_found /analytics: get: tags: - analytics summary: Get Analytics Data security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: getAnalyticsData description: | Get Analytics Data parameters: - $ref: "#/components/parameters/PageQueryParam" - $ref: "#/components/parameters/LimitQueryParam" - $ref: "#/components/parameters/FromQueryParam" - $ref: "#/components/parameters/ToQueryParam" - $ref: "#/components/parameters/AnalyticStatusQueryParam" - $ref: "#/components/parameters/AnalyticFilterByQueryParam" - $ref: "#/components/parameters/AnalyticFilterQueryParam" - $ref: "#/components/parameters/SmartSearchQueryParam" - $ref: "#/components/parameters/AnalyticOrderByQueryParam" - $ref: "#/components/parameters/OrderTypeQueryParam" - $ref: "#/components/parameters/TimezoneQueryParam" responses: "200": description: | Sucess Get Analytics Data. content: application/json: schema: $ref: "#/components/schemas/AnalyticsListSucessResponsetBody" "400": description: | Bad Request ###### Produces: * page_should_be_integer * page_should_be_greater_than_0 * limit_should_be_integer * limit_should_be_greater_than_0 * missing_required_parameter_from * from_format_should_be_yyyy-mm-dd * missing_required_parameter_to * to_format_should_be_yyyy-mm-dd * missing_required_parameter_filter_by * invalid_status_value * filter_by_can_only_be_subject_or_sender_or_recipient_or_domain * smart_search_should_be_true_or_false * orderby_can_only_be_subject_or_sender_or_recipient_or_domain * ordertype_should_be_asc_or_desc "401": $ref: "#/components/responses/Unauthorized" /analytics/csv: get: tags: - analytics summary: Export Analytics data in CSV file security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: exportAnalyticsDataCSV description: | Export Analytics data in CSV file parameters: - $ref: "#/components/parameters/FromQueryParam" - $ref: "#/components/parameters/ToQueryParam" - $ref: "#/components/parameters/AnalyticStatusQueryParam" - $ref: "#/components/parameters/AnalyticFilterByQueryParam" - $ref: "#/components/parameters/AnalyticFilterQueryParam" - $ref: "#/components/parameters/SmartSearchQueryParam" - $ref: "#/components/parameters/AnalyticOrderByQueryParam" - $ref: "#/components/parameters/OrderTypeQueryParam" - $ref: "#/components/parameters/TimezoneQueryParam" responses: "200": description: Analytics CSV data content: text/csv: schema: type: string example: > 1871534200146968576,DEFER,"Fwd: Test",test@emailchef.com,test@live.com,"Wednesday, February 21 2024 7:48 AM"," Connected to 104.47.51.161 but connection died. (#4.4.2) 1871533807186821120,DEFER,"Test send",test@emailchef.com,test@live.com,"Wednesday, February 21 2024 7:47 AM"," Connected to 104.47.55.161 but connection died. (#4.4.2) "400": description: | Bad Request ###### Produces: * missing_required_parameter_from * from_format_should_be_yyyy-mm-dd * missing_required_parameter_to * to_format_should_be_yyyy-mm-dd * missing_required_parameter_filter_by * invalid_status_value * filter_by_can_only_be_subject_or_sender_or_recipient_or_domain * smart_search_should_be_true_or_false * orderby_can_only_be_subject_or_sender_or_recipient_or_domain * ordertype_should_be_asc_or_desc "401": $ref: "#/components/responses/Unauthorized" "/analytics/{Id}": get: tags: - analytics summary: Get Analytics Single Item by ID security: - ApiKeyAuth: [] - consumerKey: [] consumerSecret: [] operationId: getAnalyticsDataByID description: | Get Analytics Data by ID parameters: - $ref: "#/components/parameters/IdParam" responses: "200": description: | Sucess Response body contains the Analytic Item requested by ID. content: application/json: schema: $ref: "#/components/schemas/AnalyticMailItem" "400": description: | Bad Request ###### Produces: * XXXXXXX content: application/json: schema: $ref: "#/components/schemas/CommonBadRequestResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found The Analytic ID was not found content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: email_not_found /user/consumerKeys: get: operationId: listConsumerKeys tags: - consumerkey summary: Get Consumer Keys list security: - ApiKeyAuth: [] description: > Get Consumer Keys list Note: Consumer Keys listing is not allwed when authenticated via Consumer Key. responses: "200": description: | Sucess Consumer Keys list content: application/json: schema: $ref: "#/components/schemas/ConsumerKeyListSucessResponsetBody" "401": $ref: "#/components/responses/Unauthorized" post: operationId: createConsumerKey tags: - consumerkey summary: Create Consumer Key security: - ApiKeyAuth: [] description: > Create new Consumer Key Note: Consumer Key creation is not allwed when authenticated via Consumer Key. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ConsumerKeyCreateRequestBody" responses: "201": description: | Sucess Consumer Key Created Sucessfully. content: application/json: schema: $ref: "#/components/schemas/ConsumerKeyCreateResponseBody" links: DeleteConsumerKey: operationId: deleteConsumerKey parameters: consumerKey: $response.body#/consumerKey "401": $ref: "#/components/responses/Unauthorized" "/user/consumerKeys/{consumerKey}": delete: operationId: deleteConsumerKey tags: - consumerkey summary: Delete Consumer Key security: - ApiKeyAuth: [] description: > Delete Consumer Key Note: Consumer Key deletion is not allwed when authenticated via Comsumer Key. parameters: - $ref: "#/components/parameters/ConsumerKeyPathParam" responses: "200": description: | Sucess Consumer Key was deleted. content: application/json: schema: $ref: "#/components/schemas/CommonSuccessResponseBody" "401": $ref: "#/components/responses/Unauthorized" "404": description: | Not Found Please verify the Consumer Key is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: key_not_found components: schemas: AuthenticationLoginRequestBody: additionalProperties: false properties: email: type: string format: email description: The email of turboSMTP account password: type: string writeOnly: true description: The password of turboSMTP account no_expire: type: boolean default: false description: >-2 **false**: authentication will expire after 2 hours. **true**: authentication will keep you signed in, and will never expire. (Use [/authentication/deauthorize](#/authentication/AuthenticationLogout) to logout and release your an API Key) required: - email - password example: email: developer@yourdomain.com password: yourTurboSmtpPassword no_expire: true AuthenticationLoginSucessResponsetBody: additionalProperties: false properties: auth: type: string description: API Key to be used in authorization header example: auth: f8efa7be4e7457c463e8b800e1f11f92072d272c ChangePasswordRequestBody: additionalProperties: false properties: current_password: type: string description: Current Password. password: type: string description: New Password to be used. confirm_password: type: string description: New Password to be used. required: - current_password - password - confirm_password example: current_password: 6SwHbc96dyE8 password: SMkhhf4J686P confirm_password: SMkhhf4J686P SendSecretTokenResetPasswordRequestBody: additionalProperties: false properties: email: type: string format: email example: developer@turboSMTP.com description: turboSMTP account email address. required: - email example: email: developer@turboSMTP.com UpdateResetPasswordRequestBody: additionalProperties: false properties: password: type: string description: New Password to be used. confirm_password: type: string description: New Password to be used. token: type: string description: Reset Password Token required: - password - confirm_password - token example: password: SMBBBf4J686P confirm_password: SMBBBf4J686P token: 781d4b44aaf5de86dc0a7e1ca2dc409f UserDetails: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - $ref: "#/components/schemas/PhoneNumber" - type: object properties: active: type: boolean example: true description: True if the account is active, false if the account is clossed. gateway: type: - string - "null" example: q1 description: The Sending Machine Name. default: null ip: type: - integer - "null" format: int64 example: 3354675819 description: The Sending Machine IP. default: null datecreated: $ref: "#/components/schemas/CustomDateTimeFormat" example: 2022-04-20 11:24:12 description: Account creation date. domain: type: - integer - "null" format: int64 description: Account domain. default: null example: null parentid: type: - integer - "null" format: int64 description: Accont Parent Id. default: null example: null ipClusterId: type: - integer - "null" format: int64 description: Cluster used for account sending. default: null example: null whiteLabeled: type: boolean description: True if account is whitelabeled. example: true sendblasterOnly: type: boolean description: True if account is related to SendBlaster only. example: false default: false executiveAccount: type: boolean description: True if account is executive example: false default: false id: type: integer format: int64 description: Account id example: 20823223 firstName: type: string description: The first name of the account owner. example: Jhon lastName: type: string description: The last name of the account owner. example: Doe companyName: type: - string - "null" description: The Copany Name of the account owner. example: Refreshing Soda Inc. address1: type: - string - "null" description: Address Line 1 of the account owner. example: 51 Guild Street address2: type: - string - "null" description: Address Line 2 of the account owner. example: 1st Floor city: type: - string - "null" description: City. example: London region: type: - string - "null" description: Region. example: null zipCode: type: - integer - "null" format: int64 description: Zip Code. example: null country: type: - string - "null" description: Country. example: null siteUrl: type: - string - "null" description: Site url. example: null companyDescription: type: - string - "null" description: Company Description. example: null timezone: type: string description: Timezone Offset example: -07:00 lang: type: string description: Language. example: en accountID: type: integer format: int64 description: Account id. example: 20823223 first_login_wizard: type: boolean description: If true, will show setup wizard to the user. example: true email_confirmation: type: boolean description: True if the email address has been confirmed. example: true account_activation: type: boolean description: True if account has been activated. example: true dns_configuration: type: boolean description: True if DNS has been setup. example: true account_settings: type: boolean description: True if user has setup account settings. example: true alert_settings: type: boolean description: True if alert settings have been setup. example: true integration: type: boolean description: True if integration has been setup. example: true ConsumerKeyCreateRequestBody: type: object additionalProperties: false properties: label: type: string description: Consumer Key label. example: QAkey. ConsumerKeyCreateResponseBody: type: object additionalProperties: false properties: consumerKey: type: string description: Consumer Key example: b914ad238d0e8e8851b81e86ce46ae1d consumerSecret: type: string description: Consumer Secret example: JOSenWTYopGjhZ1CDvsEbcK9PNUA06Xy ConsumerKey: type: object additionalProperties: false properties: consumerKey: type: string description: Consumer Key example: b914ad238d0e8e8851b81e86ce46ae1d label: type: string description: Consumer Key label. example: QAkey. creation_time: $ref: "#/components/schemas/CustomDateTimeFormat" description: The time the consumer key was created. example: 2021-03-17 00:00:00 ips: type: array description: IP addresses restricted to this consumer key. Empty array means no restriction. items: type: string is_legacy: type: boolean description: True if this is a legacy consumer key. permissions: type: array description: Permissions granted to this consumer key. items: type: string ConsumerKeyListSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/ConsumerKey" example: count: 2 results: - consumerKey: bff5c9436b6da9fe3c1d3379e7dc0f21 label: QA creation_time: 2023-10-12 11:58:11 - consumerKey: 1027d089da21adfc7f08dc14303571f3 label: Staging creation_time: 2023-08-02 17:18:00 EmailRequestBody: $ref: "#/components/schemas/Email-2" SendSucessResponsetBody: type: object additionalProperties: false properties: message: type: string example: OK mid: type: integer format: int64 example: 1688566310828572700 minimum: 0 maximum: 8446744073709552000 description: message ID SendBadRequestResponseBody: type: object additionalProperties: false properties: message: type: string example: error errors: type: array items: type: string example: - missing or not valid sender email (from) SendUnauthorizedResponseBody: type: object additionalProperties: false properties: errorCode: type: integer example: 3 message: type: string example: Invalid authorization token details: type: string example: "No authorization key was specified for request: POST /api/mail/send" Subaccount: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - $ref: "#/components/schemas/SubaccountIDStatusBase" - $ref: "#/components/schemas/SubaccountBase" SubaccountCreateRequest: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - $ref: "#/components/schemas/SubaccountBase" - $ref: "#/components/schemas/SubaccountPasswordConfirmPassword" required: - email - password - confirm_password - first_name - last_name - ip - policy_agree SubaccountUpdateRequest: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/SubaccountBase" - $ref: "#/components/schemas/SubaccountPasswordConfirmPasswordOptional" required: - first_name - last_name - ip - policy_agree SubAccountListSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/SubaccountListItem" example: count: 2 results: - active: true email: subaccount-1@yourdomain.om subaccount_id: 19302132 ip: 199.244.75.250 last_used: 2022-11-20 22:44:07 limit: 16 plan_expiration: 2023-01-17 00:00:00 sent: 2 plan_limit_interval: Monthly - active: true email: subaccount-2@yourdomain.om subaccount_id: 19302133 ip: 199.244.75.250 last_used: 2022-11-19 21:04:07 limit: 50 plan_expiration: 2023-01-17 00:00:00 sent: 34 plan_limit_interval: Monthly SubaccountActivePlan: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/SubaccountIDStatusBase" - $ref: "#/components/schemas/SubaccountIP" - $ref: "#/components/schemas/SubaccountPlanBase" AgencySettings: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Logo" - $ref: "#/components/schemas/BaseAgencySettings" EmailValidatorSubscription: type: object additionalProperties: false required: - currency - free_credits - free_credits_used - last_used_period - latest_period_start_date - paid_credits - period_expiration_date - remaining_free_credit properties: currency: $ref: "#/components/schemas/Currency" free_credits: type: integer format: int32 minimum: 0 example: 3000 description: Ammount of allocated free credits. free_credits_used: type: integer format: int32 minimum: 0 example: 200 description: Ammount of used free credits. last_used_period: $ref: "#/components/schemas/NullableCustomDateTimeFormat" example: 2022-11-20 00:00:00 description: Last time credit was used. latest_period_start_date: $ref: "#/components/schemas/NullableCustomDateTimeFormat" example: 2022-11-09 00:00:00 description: Free credit period start date (renewed each cycle). period_expiration_date: $ref: "#/components/schemas/NullableCustomDateTimeFormat" example: 2022-12-09 00:00:00 description: Free credit period expiration date. paid_credits: type: number format: currency example: 437.456 minimum: 0 description: Amount of remaining money specified in the 'currency' field value currency. remaining_free_credit: type: integer format: int32 minimum: 0 example: 2800 description: Ammount of remaining free credits. EmailValidatorList: type: object additionalProperties: false properties: id: type: integer description: Email validation list id. example: 2406 creation_time: $ref: "#/components/schemas/CustomDateTimeFormat" description: Date and Time of the validation list creation. example: 2021-03-17 08:56:00 file_name: type: string description: File name of the uploaded file. example: BusinessProspects.txt is_processed: type: boolean description: True if the validation list was already processed. example: true percentage: type: integer description: Describes the percentage progress of validation list. example: 83 total_emails: type: integer description: Amount of email addresses in the validation list. example: 314 total_processed: type: integer description: Describes the count of email addresses processed so far. example: 28 status_summary: type: array items: $ref: "#/components/schemas/EmailValidatorStatusSummaryItem" example: - status: valid total: 2 - status: invalid total: 5 EmailValidatorSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/EmailValidatorList" example: count: 2 results: - id: 2406 creation_time: 2021-03-17 00:00:00 file_name: BusinessProspects.txt is_processed: true percentage: 100 total_emails: 158 total_processed: 158 - id: 2407 creation_time: 2021-03-21 00:00:00 file_name: OldContacts.txt is_processed: false percentage: 0 total_emails: 158 total_processed: 0 EmailValidationUploadResponse: type: object additionalProperties: false properties: list_id: type: integer description: List Identifier example: 10093 total_emails: type: integer description: Total emails found in uploaded file example: 314 EmailValidatorMailDetails: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - $ref: "#/components/schemas/EmailValidatorMailSharedDetails" - type: object properties: email: type: string example: username@gmail.com description: Email address. May contain invalid formats (e.g., '@') when validation fails, to show what was submitted. did_you_mean: type: - string - "null" example: the-user@gmail.com description: Suggestive Fix for an email typo or [null]. account: type: string example: username description: The portion of the email address before the "@" symbol. firstname: type: - string - "null" example: Jhon description: The first name of the owner of the email when available or [null]. lastname: type: - string - "null" example: Doe description: The last name of the owner of the email when available or [null]. gender: type: - string - "null" example: female description: The gender of the owner of the email when available or [null]. country: type: - string - "null" example: null description: The country of the IP passed in or [null] region: type: - string - "null" example: null description: The region/state of the IP passed in or [null] city: type: - string - "null" example: null description: The city of the IP passed in or [null] zipcode: type: - integer - "null" example: null description: The zipcode of the IP passed in or [null] processed_at: $ref: "#/components/schemas/CustomDateTimeFormat" example: 2021-03-17 00:00:00 description: The date time the email was validated. EmailValidatorValidatedMailsResults: type: object additionalProperties: false properties: count: type: integer description: Count of vaidated email addresses in the list. processed: type: integer description: Number of processed email addresses in the list. results: type: array description: Array of validated email addresses in the list. items: $ref: "#/components/schemas/EmailValidatorMailDetailsBasic" EmailAddressRequestBody: type: object additionalProperties: false required: - email properties: email: type: string description: email address to validate format: email example: developer@yourcompany.com CommonSuccessResponseBody: additionalProperties: false properties: message: type: string enum: - success example: message: success CommonMessageResponseBody: type: object additionalProperties: false properties: message: type: string CommonBadRequestResponseBody: additionalProperties: false properties: message: type: string example: message: missing_required_parameter Email: type: object properties: email: type: string format: email example: username@gmail.com required: - email PhoneNumber: type: object properties: phone_number: type: string example: "5493513164544" description: Phone Number required: - phone_number AuthorizationError: type: object additionalProperties: false properties: message: type: string enum: - missing_authorization_key - invalid_authorization_key ChangePasswordBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - empty_request_body - password_is_missing - confirm_password_is_missing - current_password_is_missing - current_password_can_not_be_empty - password_should_equal_confirm_password - new_password_should_not_equal_current_password example: message: new_password_should_not_equal_current_password CheckValidityTokenResetPasswordBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - forgot_password_token_is_missing example: message: forgot_password_token_is_missing UpdateResetPasswordBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - empty_request_body - password_is_missing - confirm_password_is_missing - current_password_is_missing - current_password_can_not_be_empty - password_should_equal_confirm_password - new_password_should_not_equal_current_password example: message: new_password_should_not_equal_current_password SendSecretTokenResetPasswordBadRequestResponseBody: additionalProperties: false properties: message: type: string example: message: empty_request_body attachment: type: object additionalProperties: false properties: content: type: string description: Base64 encoded content of the attachment example: dXBsb2FkZXIxQGdtYWlsLmNvbQ0KdXBsb2FkZXIyQGdtYWlsLmNvbQ0KYWJjMQ== content_id: type: string description: | Content ID for referencing embedded images via CID in HTML content. Valid formats include: - UUID (e.g. "550e8400-e29b-41d4-a716-446655440000") - Timestamp + suffix (e.g. "20231012-abc123") - Simple incremental ID (e.g. "1") - Base64 encoded string (e.g. "c29tZV91bmlxdWUfaWQ=") - Custom format (e.g. "img_001_2023") name: type: string description: filename of the attachment example: email.ico type: type: string description: mime type of the content you are attaching example: image/gif Email-2: type: object additionalProperties: false required: - from - to properties: from: type: string pattern: ^.*<(.+)>$|^.+@.+$ description: | Sender information using either: - Email only format (user@example.com) - Display name with email (Name ) to: type: string description: comma-separated recipients emails list subject: type: - string - "null" maxLength: 700 description: email subject cc: type: - string - "null" description: comma-separated copy emails list bcc: type: - string - "null" description: comma-separated hidden copy emails list content: type: - string - "null" description: text content of the email html_content: type: - string - "null" description: html content of the email custom_headers: type: - object - "null" additionalProperties: type: string description: > email additional headers, use any additional header like standard ones List-Unsubscribe (to allow users to easily unsubscribe), X-Entity-Ref-ID (to handle how gmail and other clients group threads), and your own ones. reference_id: type: - string - "null" description: custom argument included within an email to be added to the Event Webhook response. X-campaign-ID: type: - string - "null" description: custom argument included within an email identify the campaign the email belongs to. mime_raw: type: - string - "null" description: mime message which replaces content and hmtl content attachments: type: array description: array of attachment objects items: $ref: "#/components/schemas/attachment" SuppressionImportJson: type: object additionalProperties: false required: - type - content properties: type: type: string enum: - manual example: manual reason: type: string description: Specifies a reason for suppressing imported email address/addresses content: type: array minItems: 1 description: List of email addresses to suppress (at least one required). items: type: string format: email example: type: manual reason: schemathesis-test content: - schemathesis-test@example.com SuppressionImportFile: type: object additionalProperties: false required: - type - file properties: type: type: string enum: - file example: file reason: type: string description: Specifies a reason for suppressing imported email address/addresses file: type: string format: binary description: | CSV or TXT file containing email addresses (one per line). Supported formats: text/csv (CSV), text/plain (TXT). EmailAddress: type: string format: email example: username@gmail.com SuppressionUploadResponse: type: object additionalProperties: false properties: status: type: string valid: type: array items: $ref: "#/components/schemas/EmailAddress" invalid: type: array items: type: string example: status: success valid: - valid.email.1@gmail.com - valid.email.2@gmail.com invalid: - invalid@email Page: type: - integer - "null" default: 1 minimum: 1 description: Page number. Must be an integer greater than 0. example: 1 PageLimit: type: - integer - "null" default: 10 minimum: 1 description: The number of rows per page to return. Must be an integer greater than 0. example: 10 FromDate: type: string format: date description: Start date example: 2020-01-01 ToDate: type: string format: date description: End date example: 2025-12-31 Timezone: type: string description: Timezone Offset example: -07:00 SuppressionFilter: type: string description: Query to search example: "" SuppressionSource: type: string enum: - manual - bounce - spam - unsubscribe - validation_failed SuppressionFilterBy: description: Filter by type: array items: $ref: "#/components/schemas/SuppressionSource" example: [] SmartSearch: type: - boolean - "null" description: Smart search example: false default: false SuppressionOrderBy: description: Field to sort by type: string enum: - date - source - recipient - reason default: date example: date OrderType: type: string enum: - asc - desc description: Order Ascending or Descending. default: desc example: desc CustomDateTimeFormat: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ Suppression: type: object additionalProperties: false properties: date: $ref: "#/components/schemas/CustomDateTimeFormat" example: 2021-03-17 00:00:00 sender: type: - string - "null" source: $ref: "#/components/schemas/SuppressionSource" subject: type: string example: September Newsletter recipient: type: - string - "null" format: email reason: type: - string - "null" example: 550 Error SuppressionsSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/Suppression" example: count: 5 results: - date: 2021-03-17 00:00:00 sender: andrea@emailchef.com source: bounce subject: Newsletter - September 2022 recipient: bounce1@turbo-smtp.com reason: 550 Error - date: 2021-03-15 00:00:00 sender: alberto@emailchef.com source: manual subject: "" recipient: bounce2@turbo-smtp.com reason: manual inserted - date: 2021-03-14 00:00:00 sender: alberto@emailchef.com source: spam subject: Newsletter - September 2022 recipient: topolino@turbo-smtp.com reason: spam complaint - date: 2021-03-14 00:00:00 sender: alberto@emailchef.com source: unsubscribe subject: Newsletter - September 2022 recipient: pippo@turbo-smtp.com reason: unsubscribe from list pippo - date: 2021-03-13 00:00:00 sender: alberto@emailchef.com source: validation_failed subject: Newsletter - September 2022 recipient: minnie@turbo-smtp.com reason: validation failed last import Filter: type: string description: Query to search example: "" SuppressionRestrictBy: type: string enum: - sender - recipient - reason - subject description: Field to restrict by example: sender SuppressionOperator: type: string enum: - include - exclude description: XXX example: include SuppressionRestriction: type: object additionalProperties: false description: Restriction properties: by: $ref: "#/components/schemas/SuppressionRestrictBy" operator: $ref: "#/components/schemas/SuppressionOperator" filter: type: string example: a smart_search: $ref: "#/components/schemas/SmartSearch" SuppressionRestrictions: type: array items: $ref: "#/components/schemas/SuppressionRestriction" description: xxxx SuppressionFilterRequestBody: type: object properties: from: $ref: "#/components/schemas/FromDate" to: $ref: "#/components/schemas/ToDate" tz: $ref: "#/components/schemas/Timezone" filter: $ref: "#/components/schemas/Filter" filter_by: $ref: "#/components/schemas/SuppressionFilterBy" smart_search: $ref: "#/components/schemas/SmartSearch" restrict: $ref: "#/components/schemas/SuppressionRestrictions" required: - from - to SuppressionFilterOrderRequestBody: allOf: - $ref: "#/components/schemas/SuppressionFilterRequestBody" - type: object properties: orderby: $ref: "#/components/schemas/SuppressionOrderBy" ordertype: $ref: "#/components/schemas/OrderType" SuppressionFilterOrderPageRequestBody: unevaluatedProperties: false allOf: - type: object properties: page: $ref: "#/components/schemas/Page" limit: $ref: "#/components/schemas/PageLimit" - $ref: "#/components/schemas/SuppressionFilterOrderRequestBody" SuppressionBulkDeleteRequestBody: type: array minItems: 1 description: List of email addresses to delete (at least one required). items: type: string format: email SuppressionsDeleteSuccess: type: object additionalProperties: false properties: success: type: boolean example: success: true Country: type: object additionalProperties: false properties: iso_code: type: string example: US currency: type: string example: USD flag: type: string example: 🇺🇸 name: type: string example: United States phonecode: type: string example: "1" CountryList: type: array items: $ref: "#/components/schemas/Country" example: - iso_code: AF currency: AFN flag: 🇦🇫 name: Afghanistan phonecode: "93" - iso_code: AX currency: EUR flag: 🇦🇽 name: Aland Islands phonecode: +358-18 - iso_code: AL currency: ALL flag: 🇦🇱 name: Albania phonecode: "355" State: type: object additionalProperties: false properties: name: type: string example: Alabama iso_code: type: string example: AL country_code: type: string example: US type: type: - integer - "null" example: null StateList: type: array items: $ref: "#/components/schemas/State" example: - name: Alabama iso_code: AL country_code: US type: null - name: Alaska iso_code: AK country_code: US type: null - name: American Samoa iso_code: AS country_code: US type: null BuyEmailValidatorCreditsRequest: type: object additionalProperties: false properties: amount: type: integer example: 320 description: Amount of money to use for purchase BuyEmailValidatorCreditsSucessResponse: type: object additionalProperties: false properties: url: type: string example: http://bs.dev.serversmtp.com/index.php/guest/payment_information/form/amsyUJvFeW0fkjLqbcTKMCBRZDi2AdIH description: Url to complete payment BuyEmailValidatorCreditsBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - missing_required_parameter_amount - amount_should_be_integer - amount_should_not_be_less_than_15 - amount_should_not_be_higher_than_1800 example: message: amount_should_be_integer Currency: type: string description: Currency example: $ enum: - $ - € - £ x-enum-varnames: - Dollar - Euro - Pound NullableCustomDateTimeFormat: type: - string - "null" pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ EmailValidatorUploadBadRequestResponseBody: additionalProperties: false properties: message: type: string example: message: missing_upload_file EmailValidatorStatusSummaryItem: type: object additionalProperties: false properties: status: type: string enum: - valid - invalid - catch_all - unknown - spamtrap - abuse - do_not_mail example: valid description: > The status of the email address you are validating. DELIVERABILITY STATUS EXPLANATION valid: These are emails that were determined to be valid and safe to email to, they will have a very low bounce rate of under 2%. If you receive bounces it can be because your IP might be blacklisted where our IP was not. Sometimes the email accounts exist, but they are only accepting mail from people in their contact lists. Sometimes you will get throttle on number of emails you can send to a specific domain per hour. It's important to look at the SMTP Bounce codes to determine why. invalid: These are emails that were determined to be invalid, please delete them from your mailing list. catch-all: These emails are impossible to validate without sending a real email and waiting for a bounce. The term Catch-all means that the email server tells you that the email is valid, whether it's valid or invalid. If you want to email these addresses, we suggest you segment them into a catch-all group and be aware that some of these will most likely bounce. spamtrap: These emails are believed to be spamtraps and should not be mailed. We have technology in place to determine if certain emails should be classified as spamtrap. We don't know all the spamtrap email addresses, but we do know a lot of them. abuse: These emails belong to people who are known to click the abuse links in emails, hence abusers or complainers. We recommend not emailing these addresses. do_not_mail: These emails belong to companies, role-based, or people you just want to avoid emailing to. They are broken down into 6 sub-categories "disposable","toxic", "role_based", "role_based_catch_all", "global_suppression" and "possible_trap". You should decide if you want to email these address. They are valid email addresses, but shouldn't be mailed in most cases. unknown: These emails we weren't able to validate for one reason or another. Typical cases are "Their mail server was down" or "the anti-spam system is blocking us". In most cases, 80% unknowns are invalid/bad email addresses. total: type: integer description: Ammount of emails in the status within the list. example: 12 EmailValidatorListDeleteSuccess: type: object additionalProperties: false properties: success: type: boolean example: success: true EmailValidatorValidateListBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - list_already_validated - insufficient_credit example: message: list_already_validated EmailValidatorMailSharedDetails: type: object properties: status: type: string enum: - valid - invalid - catch_all - unknown - spamtrap - abuse - do_not_mail example: valid description: > The status of the email address you are validating. DELIVERABILITY STATUS EXPLANATION valid: These are emails that were determined to be valid and safe to email to, they will have a very low bounce rate of under 2%. If you receive bounces it can be because your IP might be blacklisted where our IP was not. Sometimes the email accounts exist, but they are only accepting mail from people in their contact lists. Sometimes you will get throttle on number of emails you can send to a specific domain per hour. It's important to look at the SMTP Bounce codes to determine why. invalid: These are emails that were determined to be invalid, please delete them from your mailing list. catch-all: These emails are impossible to validate without sending a real email and waiting for a bounce. The term Catch-all means that the email server tells you that the email is valid, whether it's valid or invalid. If you want to email these addresses, we suggest you segment them into a catch-all group and be aware that some of these will most likely bounce. spamtrap: These emails are believed to be spamtraps and should not be mailed. We have technology in place to determine if certain emails should be classified as spamtrap. We don't know all the spamtrap email addresses, but we do know a lot of them. abuse: These emails belong to people who are known to click the abuse links in emails, hence abusers or complainers. We recommend not emailing these addresses. do_not_mail: These emails belong to companies, role-based, or people you just want to avoid emailing to. They are broken down into 6 sub-categories "disposable","toxic", "role_based", "role_based_catch_all", "global_suppression" and "possible_trap". You should decide if you want to email these address. They are valid email addresses, but shouldn't be mailed in most cases. unknown: These emails we weren't able to validate for one reason or another. Typical cases are "Their mail server was down" or "the anti-spam system is blocking us". In most cases, 80% unknowns are invalid/bad email addresses. sub_status: type: string enum: - "" - antispam_system - greylisted - mail_server_temporary_error - forcible_disconnect - mail_server_did_not_respond - timeout_exceeded - failed_smtp_connection - mailbox_quota_exceeded - exception_occurred - possible_trap - role_based - global_suppression - mailbox_not_found - no_dns_entries - failed_syntax_check - possible_typo - unroutable_ip_address - leading_period_removed - does_not_accept_mail - alias_address - role_based_catch_all - disposable - toxic example: "" description: > The sub-status of the email address you are validating. alias_address: (valid) These emails addresses act as forwarders/aliases and are not real inboxes, for example if you send an email to forward@example.com and then the email is forwarded to realinbox@example.com. It's a valid email address and you can send to them, it's just a little more information about the email address. We can sometimes detect alias email addresses and when we do we let you know. antispam_system: (unknown) These emails have anti-spam systems deployed that are preventing us from validating these emails. does_not_accept_mail: (invalid) These domains only send mail and don't accept incoming mail. exception_occurred: (unknown) These emails caused an exception when validating. failed_smtp_connection: (unknown) These emails belong to a mail server that won't allow an SMTP connection. Most of the time, these emails will end up being invalid. failed_syntax_check: (Invalid) Emails that fail RFC syntax protocols forcible_disconnect: (Unknown) These emails belong to a mail server that disconnects immediately upon connecting. Most of the time, these emails will end up being invalid. global_suppression: (do_not_mail) These emails are found in many popular global suppression lists (GSL), they consist of known ISP complainers, direct complainers, purchased addresses, domains that don't send mail, and known litigators. greylisted: (Unknown) Emails where we are temporarily unable to validate them. A lot of times if you resubmit these emails they will validate on a second pass. leading_period_removed: (valid) If a valid gmail.com email address starts with a period '.' we will remove it, so the email address is compatible with all mailing systems. mail_server_did_not_respond- (unknown) These emails belong to a mail server that is not responding to mail commands. Most of the time, these emails will end up being invalid. mail_server_temporary_error: (unknown) These emails belong to a mail server that is returning a temporary error. Most of the time, these emails will end up being invalid. mailbox_quota_exceeded: (invalid) These emails exceeded their space quota and are not accepting emails. These emails are marked invalid. mailbox_not_found: (invalid) These emails addresses are valid in syntax, but do not exist. These emails are marked invalid. no_dns_entries: (invalid) These emails are valid in syntax, but the domain doesn't have any records in DNS or have incomplete DNS Records. Therefore, mail programs will be unable to or have difficulty sending to them. These emails are marked invalid. possible_trap: (do_not_mail) These emails contain keywords that might correlate to possible spam traps like spam@ or @spamtrap.com. Examine these before deciding to send emails to them or not. possible_typo: (invalid) These are emails of commonly misspelled popular domains. These emails are marked invalid. role_based: (do_not_mail) These emails belong to a position or a group of people, like sales@ info@ and contact@. Role-based emails have a strong correlation to people reporting mails sent to them as spam and abuse. role_based_catch_all: (do_not_mail) These emails are role-based and also belong to a catch_all domain. timeout_exceeded: (unknown) These emails belong to a mail server that is responding extremely slow. Most of the time, these emails will end up being invalid. unroutable_ip_address: (invalid) These emails domains point to an un-routable IP address, these are marked invalid. disposable: (do_not_mail) These are temporary emails created for the sole purpose to sign up to websites without giving their real email address. These emails are short lived from 15 minutes to around 6 months. There is only 2 values (True and False). If you have valid emails with this flag set to TRUE, you shouldn't email them. toxic: (do_not_mail) These email addresses are known to be abuse, spam, or bot created emails. If you have valid emails with this flag set to TRUE, you shouldn't email them. free_email: type: boolean example: true description: True if the email address comes from a free email service provider. domain: type: string example: gmail.com description: The portion of the email address after the "@" symbol. domain_age_days: type: - integer - "null" example: 9964 description: Age of the email domain in days or [null]. smtp_provider: type: - string - "null" example: google description: The SMTP Provider of the email or [null]. mx_found: type: boolean example: true description: True if the domain have an MX record. mx_record: type: - string - "null" example: gmail-smtp-in.l.google.com description: The preferred MX record of the domain or [null]. EmailValidatorMailDetailsBasic: unevaluatedProperties: false type: object properties: email: type: string description: | Email address as submitted. May contain invalid formats (e.g., '@') for failed validations. Check 'status' field to determine if address is valid. example: username@gmail.com id: type: integer example: 2047 description: The id of the email address required: - email - id allOf: - $ref: "#/components/schemas/EmailValidatorMailSharedDetails" EmailValidatorListEmailDetails: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - type: object properties: email: type: string example: username@gmail.com description: Email address. May contain invalid formats (e.g., '@') when validation fails, to show what was submitted. account_id: type: integer example: 20823223 description: Email validator account id. created_at: $ref: "#/components/schemas/CustomDateTimeFormat" example: 2021-03-17 00:00:00 description: The date time the email was inserted into turboSMTP database after being validated. did_you_mean: type: string example: the-user@gmail.com description: Suggestive Fix for an email typo id: type: integer example: 18535681 description: Email Id. list_id: type: integer example: 10629 description: List Id. - $ref: "#/components/schemas/EmailValidatorMailSharedDetails" EmailValidatorValidateBadRequestResponseBody: additionalProperties: false properties: message: type: string enum: - invalid_email_address - missing_required_parameter_email example: message: invalid_email_address SubaccountIP: type: object properties: ip: type: string description: IP address to use for sending emails. example: 185.228.36.19 SubaccountActiveStatus: type: object properties: active: type: boolean description: Active subaccounts can be used for login purpose, while users can´t login to inactive subaccounts. Notice that in order to be able to send emails the subaccount subscription must also be active. User can set subaccounts to active / inactive from the dashboard. example: true required: - active SubaccountIDStatusBase: allOf: - $ref: "#/components/schemas/SubaccountIP" - $ref: "#/components/schemas/SubaccountActiveStatus" - type: object properties: subaccount_id: type: integer example: 19302132 description: Sub account Id parent_id: type: integer example: 19334162 description: Sub account parent Id SubaccountSMTPLimit: type: object properties: limit: type: integer example: 2000 description: The ammount of emails the sub account is allowed to send over the period specified by plan_limit_interval. Value -1 means no limit. required: - limit SmtpLimitInterval: type: string enum: - Daily - Monthly - Yearly example: Monthly description: > Limit interval that specifies if the sub account sending limit is specified daily, monthly or yearly. * Important Note: The limit interval allways follows the main account limit. SubaccountPlanBase: allOf: - $ref: "#/components/schemas/SubaccountSMTPLimit" - type: object properties: sent: type: integer example: 125 description: The ammount of sent emails from the sub account over the current period. last_used: $ref: "#/components/schemas/NullableCustomDateTimeFormat" example: 2021-03-17 00:00:00 description: The date time the sub account was last used. plan_expiration: $ref: "#/components/schemas/NullableCustomDateTimeFormat" example: 2023-01-17 00:00:00 description: Expiration date time of the plan. plan_limit_interval: $ref: "#/components/schemas/SmtpLimitInterval" expired: type: boolean example: false description: Expired if plan expiration date is overdue. SubaccountListItem: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/Email" - $ref: "#/components/schemas/SubaccountIDStatusBase" - $ref: "#/components/schemas/SubaccountIP" - $ref: "#/components/schemas/SubaccountPlanBase" CommmonResultResponseBody: type: object additionalProperties: false properties: result: type: boolean example: true SubaccountBase: allOf: - $ref: "#/components/schemas/SubaccountIP" - type: object properties: first_name: type: string description: subaccount owner first name minLength: 1 maxLength: 50 example: Andrea last_name: type: string description: subaccount owner last name minLength: 1 maxLength: 50 example: Willems address_1: type: - string - "null" description: Address Line 1 example: 51 Guild Street maxLength: 255 address_2: type: - string - "null" description: Address Line 2 example: 1st Floor maxLength: 255 city: type: - string - "null" description: City example: London maxLength: 100 company_name: type: - string - "null" description: Agency Name example: Refreshing Soda Inc. maxLength: 100 country: type: - string - "null" description: Country example: United Kingdom maxLength: 64 region: type: - string - "null" description: Region example: West maxLength: 100 zip_code: type: - string - "null" description: Zip Code example: NW10 9NQ maxLength: 10 phone_number: type: - string - "null" description: Phone Number example: "5493513164544" maxLength: 30 policy_agree: type: boolean description: Policy must be agreed in order to be able to create a subaccount. example: true site_url: type: - string - "null" description: Website example: https://www.refreshing-soda.com maxLength: 45 SubaccountPasswordConfirmPassword: type: object additionalProperties: false properties: password: type: string description: subaccount password minLength: 10 example: LetmeIn123! confirm_password: type: string description: subaccount confirm password minLength: 10 example: LetmeIn123! SubaccountPasswordConfirmPasswordOptional: type: object properties: password: type: string description: subaccount password minLength: 10 example: LetmeIn123! confirm_password: type: string description: subaccount confirm password minLength: 10 example: LetmeIn123! Logo: type: object properties: logoUrl: type: string BaseAgencySettings: type: object properties: agency_name: type: string description: Agency Name example: My Agency Inc. maxLength: 128 agency_website: type: string description: Agency Website example: https://www.mywebsite.com maxLength: 128 agency_footer: type: string description: Footer to be used example: My signature goes here. maxLength: 2048 AlertBase: allOf: - $ref: "#/components/schemas/Email" - type: object properties: percentage: type: integer example: 80 description: Percentage of usage that will trigger the alert maximum: 100 minimum: 0 Alert: unevaluatedProperties: false allOf: - $ref: "#/components/schemas/AlertBase" - type: object properties: id: type: integer example: 4117 description: Alert Id. AlertListSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/Alert" example: count: 2 results: - id: 4117 email: doe-jhon@yourdomain.om percentage: 50 - id: 4118 email: doe-jhon@yourdomain.om percentage: 100 AnalyticMailStatus: description: > Send Mail Status: NEW: email has been queued for delivery DEFER: email is in the queue for delivery SUCCESS: email has been delivered. OPEN: email has been opened. CLICK: email has been clicked. REPORT: email has been reported as spam. FAIL: email has bounced. SYSFAIL: email was dropped. UNSUB: email is unsubscribed. Notice that emails that fall into the above statuses can be grouped, ie Turbo-Smtp uses the following groups: 'Clicks' = 'CLICK', 'Unsubscribes' = 'UNSUB', 'Spam' = 'REPORT', 'Drop' = 'SYSFAIL', 'Queued' = 'NEW' or 'DEFER', 'Opens'= 'OPEN' or 'CLICK' or 'UNSUB' or 'REPORT', 'Delivered'= 'SUCCESS' or 'OPEN' or 'CLICK' or 'UNSUB' or 'REPORT', 'Bounce': 'FAIL'. type: string enum: - NEW - DEFER - SUCCESS - OPEN - CLICK - REPORT - FAIL - SYSFAIL - UNSUB AnalyticFilterByOption: type: string enum: - subject - sender - recipient - domain example: domain AnalyticFilterBy: description: Filter by type: array items: $ref: "#/components/schemas/AnalyticFilterByOption" example: - subject AnalyticOrderBy: description: Field to sort by. Valid values are subject, sender, recipient, or send_time. type: string enum: - subject - sender - recipient - send_time default: send_time example: send_time AnalyticMailItem: description: Sent Email type: object additionalProperties: false properties: id: type: integer format: int64 example: 1800872493473407000 description: Email Id. subject: type: string description: Email Subject. example: Business Card. sender: type: string description: Email Sender. format: email example: user@example.com recipient: type: string description: Email Recipient. format: email example: user@gmail.com send_time: type: string description: Date Time email was sent. pattern: (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) example: 2022-11-20 00:00:00 status: $ref: "#/components/schemas/AnalyticMailStatus" domain: type: string description: The portion of the sender´s email address after the "@" symbol. example: example.com recipient_domain: type: string description: The portion of the recipient´s email address after the "@" symbol. example: gmail.com contact_domain: type: string description: The domain of the contact/recipient. example: gmail.com x_campaign_id: type: string description: Value specified in the x_campaign_id custom header to track campaigns specific data. example: Offer AB Test. error: type: string description: Error returned when delivering the email message. example: "142.250.138.27 does not like recipient.\\nRemote host said: 550-5.1.1 The email account does not exist." AnalyticsListSucessResponsetBody: type: object additionalProperties: false properties: count: type: integer results: type: array items: $ref: "#/components/schemas/AnalyticMailItem" example: count: 2 results: - id: 1800872493473407000 subject: Newsletter update sender: sample@gmail.com recipient: robert-doe@elecronic-arts.com send_time: 2023-08-10 04:04:21 status: SUCCESS domain: gmail.com error: "" recipient_domain: electronic-arts.com x_campaign_id: Offer AB Test. - id: 1800871904471490600 subject: New Movies sender: sales@gmail.com recipient: jhon-doe@datamart.com send_time: 2023-08-11 04:04:21 status: FAIL domain: gmail.com error: "142.250.138.27 does not like recipient.\\nRemote host said: 550-5.1.1 The email account does not exist." recipient_domain: datamart.com x_campaign_id: Offer AB Test. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization consumerKey: type: apiKey in: header name: consumerKey consumerSecret: type: apiKey in: header name: consumerSecret responses: Unauthorized: description: > Unauthorized This API requires a valid API Key to be provided. (Use [/authentication/authorize](#/authentication/AuthenticationLogin) to obtain an API Key) Produces: * missing_authorization_key * invalid_authorization_key * account_is_inactive content: application/json: schema: $ref: "#/components/schemas/AuthorizationError" examples: MissingAuthorizationKey: summary: Missing Authorization Key value: message: missing_authorization_key InvalidAuthorizationKey: summary: Invalid / Expired Authorization Key value: message: invalid_authorization_key SuppressionsCSV: description: Suppressions CSV data content: text/csv: schema: type: string example: > Status;Subject;From;To;Date;Reason FAIL;"new email alert";msaad@emailchef.com;a.shatata@emailchef.com;2022-06-28T15:08:37.821Z;"199.187.175.11 does not like recipient. Remote host said: 550 5.1.1 : Recipient address rejected: User unknown in virtual mailbox table {199.244.75.250}{550} Giving up on 199.187.175.11. " MANUAL;;;mohamed@test.com;2022-06-18T19:51:04.914Z; FAIL;"Test sending email";msaad@emailchef.com;mshatta@yahoo.com;2021-05-03T12:21:48.000Z;"67.195.204.73 failed after I sent the message. Remote host said: 554 30 Sorry, your message to mshatta@yahoo.com cannot be delivered. This mailbox is disabled (554.30). " FAIL;"Test sending email";msaad@emailchef.com;mohamed_s_shatta@gmail.com;2021-05-03T12:21:04.000Z;"142.250.138.26 does not like recipient. Remote host said: 550-5.1.1 The email account that you tried to reach does not exist. Please try 550-5.1.1 double-checking the recipient's email address for typos or 550-5.1.1 unnecessary spaces. Learn more at 550 5.1.1 https://support.google.com/mail/?p=NoSuchUser g15si5159810otg.85 - gsmtp {199.244.75.250}{550} Giving up on 142.250.138.26. " ValidatedEmailsCSV: description: | Sucess Validated Emails by Email Validation List CSV File content: text/csv: schema: type: string example: > Status;Subject;From;To;Date;Reason FAIL;"new email alert";msaad@emailchef.com;a.shatata@emailchef.com;2022-06-28T15:08:37.821Z;"199.187.175.11 does not like recipient. Remote host said: 550 5.1.1 : Recipient address rejected: User unknown in virtual mailbox table {199.244.75.250}{550} Giving up on 199.187.175.11. " MANUAL;;;mohamed@test.com;2022-06-18T19:51:04.914Z; FAIL;"Test sending email";msaad@emailchef.com;mshatta@yahoo.com;2021-05-03T12:21:48.000Z;"67.195.204.73 failed after I sent the message. Remote host said: 554 30 Sorry, your message to mshatta@yahoo.com cannot be delivered. This mailbox is disabled (554.30). " FAIL;"Test sending email";msaad@emailchef.com;mohamed_s_shatta@gmail.com;2021-05-03T12:21:04.000Z;"142.250.138.26 does not like recipient. Remote host said: 550-5.1.1 The email account that you tried to reach does not exist. Please try 550-5.1.1 double-checking the recipient's email address for typos or 550-5.1.1 unnecessary spaces. Learn more at 550 5.1.1 https://support.google.com/mail/?p=NoSuchUser g15si5159810otg.85 - gsmtp {199.244.75.250}{550} Giving up on 142.250.138.26. " ForbiddenForActivePlan: description: > Forbidden The current active plan does not include this feature, upgrade is required to use this feature. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: feature_not_available_for_active_plan SubaccountNotFound: description: | Not Found Please verify the subaccount id is valid. content: application/json: schema: $ref: "#/components/schemas/CommonMessageResponseBody" example: message: subaccount_not_found LogoSuccess: description: | Agency Logo Url content: application/json: schema: $ref: "#/components/schemas/Logo" parameters: PageQueryParam: in: query required: false name: page schema: $ref: "#/components/schemas/Page" description: Page number example: 1 LimitQueryParam: in: query required: false name: limit schema: $ref: "#/components/schemas/PageLimit" description: The numbers of rows per page to return example: 10 FromQueryParam: in: query required: true name: from schema: $ref: "#/components/schemas/FromDate" description: Start date (format YYYY-MM-DD). Must be less than or equal to the 'to' parameter. example: 2020-01-01 ToQueryParam: in: query name: to required: true schema: $ref: "#/components/schemas/ToDate" description: End date (format YYYY-MM-DD). Must be greater than or equal to the 'from' parameter. example: 2025-12-31 TimezoneQueryParam: in: query name: tz schema: $ref: "#/components/schemas/Timezone" description: Timezone Offset example: -07:00 SuppressionFilterQueryParam: in: query name: filter required: false schema: $ref: "#/components/schemas/SuppressionFilter" description: Text to search (recipient, sender, email subject or reason for suppression) examples: byemail: value: Jhon.Doe@gmail.com summary: Search for recipient or sender. bytitle: value: September 2022 summary: Search for email title. byreason: value: Imported removal request summary: Search for imported supressions. SuppressionFilterByQueryParam: in: query name: filter_by required: false schema: $ref: "#/components/schemas/SuppressionFilterBy" SmartSearchQueryParam: in: query name: smart_search required: false schema: $ref: "#/components/schemas/SmartSearch" description: Smart search example: false SuppressionOrderByQueryParam: in: query name: orderby required: false schema: $ref: "#/components/schemas/SuppressionOrderBy" OrderTypeQueryParam: in: query required: false name: ordertype schema: $ref: "#/components/schemas/OrderType" IsoCodePathParam: in: path name: isoCode required: true description: Country ISO code (ISO 3166-1 alpha-2 format). Valid values are 2-letter uppercase country codes (e.g., US, GB, DE). Use GET /meta/countries to retrieve all valid codes. schema: type: string pattern: ^[A-Z]{2}$ example: US IdParam: name: Id in: path description: Id required: true schema: type: integer SubaccountFilterByEmailQueryParam: in: query name: filter_by_email required: false schema: description: Filter by email addresses that fully/partially match the search value. type: string example: Jhon description: Filter by email addresses that fully/partially match the search value. SubaccountFilterByActiveQueryParam: in: query name: filter_by_active required: false schema: description: Filter by subaccount active/inactive status (true=active, false=inactive). type: boolean example: true description: Filter by subaccount active/inactive status. Accepts boolean values (true or false). SubaccountFilterByIPQueryParam: in: query name: filter_by_ip[] required: false style: form explode: true schema: description: Filter by IPv4 addresses. Multiple IPs can be provided. Valid IPv4 format (e.g., 192.168.1.1). type: array items: type: string pattern: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$ description: Filter by IPv4 addresses (e.g., 192.168.1.1). Multiple IPs can be provided. SubaccountOrderByQueryParam: in: query name: order_by required: false schema: description: Field to sort by type: string enum: - email - last_used default: email example: email description: Field to sort by EmailQueryParam: name: Email in: query description: Email address. required: true schema: type: string format: email example: username@gmail.com AnalyticStatusQueryParam: in: query required: false name: status[] style: form explode: true description: > Filter by Status NEW: email has been queued for delivery DEFER: email is in the queue for delivery SUCCESS: email has been delivered. OPEN: email has been opened. CLICK: email has been clicked. REPORT: email has been reported as spam. FAIL: email has bounced. SYSFAIL: email was dropped. UNSUB: email is unsubscribed.
Notice that emails that fall into the above statuses can be grouped, ie Turbo-Smtp uses the following groups:
'Clicks' = 'CLICK', 'Unsubscribes' = 'UNSUB', 'Spam' = 'REPORT', 'Drop' = 'SYSFAIL', 'Queued' = 'NEW' or 'DEFER', 'Opens'= 'OPEN' or 'CLICK' or 'UNSUB' or 'REPORT', 'Delivered'= 'SUCCESS' or 'OPEN' or 'CLICK' or 'UNSUB' or 'REPORT', 'Bounce': 'FAIL'. schema: description: Filter by Status type: array items: $ref: "#/components/schemas/AnalyticMailStatus" AnalyticFilterByQueryParam: in: query name: filter_by required: false style: form explode: true description: Filter by schema: $ref: "#/components/schemas/AnalyticFilterBy" AnalyticFilterQueryParam: in: query name: filter required: false schema: $ref: "#/components/schemas/Filter" description: Text to search (recipient, sender, email subject or reason for suppression) examples: bysubject: value: September 2022 summary: Search for email subject. bysender: value: Sales@gmail.com summary: Search for emai sender. byrecipient: value: Jhon.Doe@gmail.com summary: Search for emai recipient. bydomain: value: gmail.com summary: Search for recipient email domain. bycampaign: value: ABC Test summary: Search for Campaign ID. AnalyticOrderByQueryParam: in: query name: orderby required: false description: Order by schema: $ref: "#/components/schemas/AnalyticOrderBy" ConsumerKeyPathParam: in: path name: consumerKey required: true description: Consumer Key schema: type: string example: b914ad238d0e8e8851b81e86ce46ae1d