Mailtrap connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Mailtrap API token with Scalekit so it can authenticate and proxy email requests on behalf of your users. Mailtrap uses Bearer Token authentication — there is no redirect URI or OAuth flow.

   1. Get a Mailtrap API token

      • Sign in to mailtrap.io and go to Settings → API Tokens.
      • Click Add Token and give it a name (for example, Agent Connect).
      • Copy the generated token.

      

   2. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Mailtrap and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., mailtrap).

   3. Add a connected account

      Connected accounts link a specific user identifier in your system to a Mailtrap API token. Add them via the dashboard for testing, or via the Scalekit API in production.

      Via dashboard (for testing)

      • Open the connection and click the Connected Accounts tab → Add account.
      • Fill in Your User’s ID and API Token, then click Save.

      Via API (for production)

      Node.js

      await scalekit.connect.upsertConnectedAccount({
        connectionName: 'mailtrap',
        identifier: 'user@example.com',
        credentials: { token: 'your-mailtrap-api-token' },
      })

      Python

      scalekit_client.connect.upsert_connected_account(
          connection_name="mailtrap",
          identifier="user@example.com",
          credentials={"token": "your-mailtrap-api-token"},
      )

4. Make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'mailtrap'
   const identifier = 'user_123'
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'mailtrap_get_accounts',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "mailtrap"
   identifier = "user_123"
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="mailtrap_get_accounts",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Sandbox clean — Delete all captured messages from a sandbox inbox, clearing it for fresh test runs
• Create api token, contact, contact field — Create a new API token with a specified name and optional resource permissions
• Delete api token, contact, contact list — Permanently delete an API token by ID
• Message forward sandbox — Forward a captured sandbox test email to a real recipient email address for live testing
• Get accounts, billing usage, contact — List all Mailtrap accounts the API token has access to
• List account accesses, api tokens, contact fields — List all user and invite account accesses with optional resource type filtering

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

mailtrap_clean_sandbox#Delete all captured messages from a sandbox inbox, clearing it for fresh test runs.1 param▾

Delete all captured messages from a sandbox inbox, clearing it for fresh test runs.

NameTypeRequiredDescription

sandbox_idintegerrequiredID of the sandbox inbox to clean.

mailtrap_create_api_token#Create a new API token with a specified name and optional resource permissions.2 params▾

Create a new API token with a specified name and optional resource permissions.

NameTypeRequiredDescription

namestringrequiredName for the new API token.

permissions_jsonstringrequiredJSON array string of permission objects. The Mailtrap API requires at least one permission.

mailtrap_create_contact#Create a new marketing contact with email address, custom fields, and contact list assignments.5 params▾

Create a new marketing contact with email address, custom fields, and contact list assignments.

NameTypeRequiredDescription

emailstringrequiredEmail address of the contact. Must be a valid email address.

first_namestringoptionalFirst name of the contact.

last_namestringoptionalLast name of the contact.

list_idsstringoptionalComma-separated list IDs to add this contact to upon creation, e.g. '123,456'.

statusstringoptionalSubscription status of the contact. Valid values: subscribed, unsubscribed.

mailtrap_create_contact_field#Create a custom contact field with a name and data type (text, integer, float, boolean, or date).3 params▾

Create a custom contact field with a name and data type (text, integer, float, boolean, or date).

NameTypeRequiredDescription

data_typestringrequiredThe data type of the contact field.

merge_tagstringrequiredLowercase short identifier with underscores used as a merge tag in email templates (e.g. company_size).

namestringrequiredThe display name for the custom contact field.

mailtrap_create_contact_list#Create a new contact list for segmenting marketing email recipients.1 param▾

Create a new contact list for segmenting marketing email recipients.

NameTypeRequiredDescription

namestringrequiredName for the new contact list, e.g. 'Monthly Newsletter Subscribers'.

mailtrap_create_domain#Create a new sending domain and receive DNS configuration records for DKIM and SPF setup.1 param▾

Create a new sending domain and receive DNS configuration records for DKIM and SPF setup.

NameTypeRequiredDescription

namestringrequiredThe domain name to add as a sending domain.

mailtrap_create_project#Create a new sandbox project to organize testing inboxes by team or application.1 param▾

Create a new sandbox project to organize testing inboxes by team or application.

NameTypeRequiredDescription

namestringrequiredThe name of the new sandbox project.

mailtrap_create_sandbox#Create a new sandbox inbox within a specific project for capturing test emails.2 params▾

Create a new sandbox inbox within a specific project for capturing test emails.

NameTypeRequiredDescription

namestringrequiredName for the new sandbox inbox.

project_idintegerrequiredID of the project in which to create the sandbox inbox.

mailtrap_create_suppression#Add an email address to the suppression list to prevent future email deliveries.4 params▾

Add an email address to the suppression list to prevent future email deliveries.

NameTypeRequiredDescription

domain_idintegerrequiredNumeric ID of the verified sending domain this suppression applies to.

emailstringrequiredEmail address to add to the suppression list.

sending_streamstringrequiredSending stream to suppress the email address on.

typestringoptionalSuppression type indicating the reason for suppression.

mailtrap_create_template#Create a new reusable email template with name, subject, and HTML/text body content.5 params▾

Create a new reusable email template with name, subject, and HTML/text body content.

NameTypeRequiredDescription

categorystringrequiredCategory to organize the template.

namestringrequiredName of the email template.

subjectstringrequiredSubject line for the email template.

html_bodystringoptionalHTML body content of the email template.

text_bodystringoptionalPlain text body content of the email template.

mailtrap_delete_api_token#Permanently delete an API token by ID. This action cannot be undone.1 param▾

Permanently delete an API token by ID. This action cannot be undone.

NameTypeRequiredDescription

token_idintegerrequiredID of the API token to permanently delete.

mailtrap_delete_contact#Permanently remove a contact by UUID or email address from the Mailtrap account. This action cannot be undone.1 param▾

Permanently remove a contact by UUID or email address from the Mailtrap account. This action cannot be undone.

NameTypeRequiredDescription

contact_identifierstringrequiredUUID or email address of the contact to permanently delete. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' or 'alice@example.com'.

mailtrap_delete_contact_list#Delete a contact list by ID. This does not delete the contacts within the list.1 param▾

Delete a contact list by ID. This does not delete the contacts within the list.

NameTypeRequiredDescription

list_idintegerrequiredThe numeric ID of the contact list to delete.

mailtrap_delete_domain#Delete a sending domain from the Mailtrap account. This action is permanent and cannot be undone.1 param▾

Delete a sending domain from the Mailtrap account. This action is permanent and cannot be undone.

NameTypeRequiredDescription

domain_idintegerrequiredThe unique numeric ID of the domain to delete.

mailtrap_delete_suppression#Remove an email address from the suppression list to re-enable email deliveries.1 param▾

Remove an email address from the suppression list to re-enable email deliveries.

NameTypeRequiredDescription

suppression_idintegerrequiredID of the suppression record to remove.

mailtrap_delete_template#Permanently delete an email template by ID.1 param▾

Permanently delete an email template by ID.

NameTypeRequiredDescription

email_template_idintegerrequiredID of the email template to delete.

mailtrap_forward_sandbox_message#Forward a captured sandbox test email to a real recipient email address for live testing.3 params▾

Forward a captured sandbox test email to a real recipient email address for live testing.

NameTypeRequiredDescription

emailstringrequiredThe real recipient email address to forward the sandbox message to.

message_idintegerrequiredThe numeric ID of the sandbox message to forward.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

mailtrap_get_accounts#List all Mailtrap accounts the API token has access to.0 params▾

List all Mailtrap accounts the API token has access to.

mailtrap_get_billing_usage#Get current billing cycle usage for Sandbox, Email API, and Email Marketing quotas.0 params▾

Get current billing cycle usage for Sandbox, Email API, and Email Marketing quotas.

mailtrap_get_contact#Retrieve a contact by UUID or email address, including their subscription status and custom fields.1 param▾

Retrieve a contact by UUID or email address, including their subscription status and custom fields.

NameTypeRequiredDescription

contact_identifierstringrequiredUUID or email address of the contact to retrieve. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' or 'alice@example.com'.

mailtrap_get_contact_list#Get details of a specific contact list by ID, including its name and contact count.1 param▾

Get details of a specific contact list by ID, including its name and contact count.

NameTypeRequiredDescription

list_idintegerrequiredNumeric ID of the contact list to retrieve. Example: 42.

mailtrap_get_domain#Get details for a specific sending domain including DNS records, DKIM keys, and verification status.1 param▾

Get details for a specific sending domain including DNS records, DKIM keys, and verification status.

NameTypeRequiredDescription

domain_idintegerrequiredID of the sending domain to retrieve.

mailtrap_get_email_log#Retrieve detailed information for a specific sent message by its ID, including delivery events and timestamps.1 param▾

Retrieve detailed information for a specific sent message by its ID, including delivery events and timestamps.

NameTypeRequiredDescription

sending_message_idstringrequiredThe unique ID of the sent message to retrieve. Obtained from the List Email Logs response.

mailtrap_get_message_spam_report#Get spam analysis score and detailed spam rule report for a captured sandbox email.2 params▾

Get spam analysis score and detailed spam rule report for a captured sandbox email.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message to analyze for spam.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

mailtrap_get_sandbox_message#Show full details of a specific captured test email including headers, HTML body, and text body.2 params▾

Show full details of a specific captured test email including headers, HTML body, and text body.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message to retrieve.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

mailtrap_get_sending_stats#Get overall email sending statistics including sent, delivered, opened, clicked, bounced, and spam counts.2 params▾

Get overall email sending statistics including sent, delivered, opened, clicked, bounced, and spam counts.

NameTypeRequiredDescription

end_datestringrequiredISO date string for the end of the stats period.

start_datestringrequiredISO date string for the start of the stats period.

mailtrap_get_stats_by_category#Get email sending statistics grouped by email category tag.3 params▾

Get email sending statistics grouped by email category tag.

NameTypeRequiredDescription

end_datestringrequiredThe end date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

start_datestringrequiredThe start date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

domain_idintegeroptionalFilter statistics to a specific sending domain by its numeric ID.

mailtrap_get_stats_by_date#Get email sending statistics grouped by date for trend analysis over a time period.3 params▾

Get email sending statistics grouped by date for trend analysis over a time period.

NameTypeRequiredDescription

domain_idintegeroptionalFilter statistics to a specific sending domain by its numeric ID.

end_datestringoptionalThe end date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

start_datestringoptionalThe start date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

mailtrap_get_stats_by_domain#Get email sending statistics grouped by sending domain for the specified date range.2 params▾

Get email sending statistics grouped by sending domain for the specified date range.

NameTypeRequiredDescription

end_datestringrequiredThe end date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

start_datestringrequiredThe start date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

mailtrap_get_stats_by_esp#Get email sending statistics grouped by recipient email service provider (Gmail, Outlook, etc.).3 params▾

Get email sending statistics grouped by recipient email service provider (Gmail, Outlook, etc.).

NameTypeRequiredDescription

end_datestringrequiredThe end date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

start_datestringrequiredThe start date for the statistics range in ISO 8601 date format (YYYY-MM-DD).

domain_idintegeroptionalFilter statistics to a specific sending domain by its numeric ID.

mailtrap_get_template#Get a single email template by ID including its name, subject, and HTML/text body content.1 param▾

Get a single email template by ID including its name, subject, and HTML/text body content.

NameTypeRequiredDescription

email_template_idintegerrequiredThe numeric ID of the email template to retrieve.

mailtrap_list_account_accesses#List all user and invite account accesses with optional resource type filtering.2 params▾

List all user and invite account accesses with optional resource type filtering.

NameTypeRequiredDescription

resource_idintegeroptionalFilter accesses by the numeric ID of the target resource.

resource_typestringoptionalFilter accesses by the type of resource they apply to.

mailtrap_list_api_tokens#List all API tokens visible to the current API token.0 params▾

List all API tokens visible to the current API token.

mailtrap_list_contact_fields#List all custom contact fields defined for the account (maximum 40 fields).0 params▾

List all custom contact fields defined for the account (maximum 40 fields).

mailtrap_list_contact_lists#List all contact lists in the Mailtrap account, with optional search filtering and pagination.3 params▾

List all contact lists in the Mailtrap account, with optional search filtering and pagination.

NameTypeRequiredDescription

limitintegeroptionalNumber of contact lists to return per page.

pageintegeroptionalPage number for pagination. Starts at 1.

searchstringoptionalSearch term to filter contact lists by name. Case-insensitive substring match.

mailtrap_list_domains#List all sending domains with their verification, DKIM, SPF, and compliance status.2 params▾

List all sending domains with their verification, DKIM, SPF, and compliance status.

NameTypeRequiredDescription

limitintegeroptionalMaximum number of domain records to return per page.

pageintegeroptionalPage number for paginated results.

mailtrap_list_email_logs#List email logs with filtering by status, date range, domain, and search. Returns sent message records with delivery status.7 params▾

List email logs with filtering by status, date range, domain, and search. Returns sent message records with delivery status.

NameTypeRequiredDescription

domain_idintegeroptionalFilter logs by sending domain ID.

end_datestringoptionalFilter logs sent on or before this date.

limitintegeroptionalNumber of log records to return per page.

pageintegeroptionalPage number for paginated results.

searchstringoptionalSearch term to filter email logs by subject, recipient, or message ID.

start_datestringoptionalFilter logs sent on or after this date.

statusstringoptionalFilter logs by delivery status.

mailtrap_list_projects#List all sandbox projects in the account. Projects are containers for organizing sandbox inboxes.0 params▾

List all sandbox projects in the account. Projects are containers for organizing sandbox inboxes.

mailtrap_list_sandbox_messages#Get captured test emails in a sandbox inbox with optional filtering by subject or sender.4 params▾

Get captured test emails in a sandbox inbox with optional filtering by subject or sender.

NameTypeRequiredDescription

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to list messages from.

limitintegeroptionalMaximum number of messages to return per page.

pageintegeroptionalPage number for paginating through sandbox messages.

searchstringoptionalSearch string to filter messages by subject or sender.

mailtrap_list_sandboxes#List all testing sandbox inboxes available for capturing test emails in development.2 params▾

List all testing sandbox inboxes available for capturing test emails in development.

NameTypeRequiredDescription

limitintegeroptionalMaximum number of sandboxes to return per page.

pageintegeroptionalPage number for paginated results.

mailtrap_list_sub_accounts#List all sub accounts belonging to a specified organization.1 param▾

List all sub accounts belonging to a specified organization.

NameTypeRequiredDescription

organization_idintegerrequiredID of the organization whose sub accounts should be listed.

mailtrap_list_suppressions#List suppressed email addresses including bounces, unsubscribes, and spam complaints.3 params▾

List suppressed email addresses including bounces, unsubscribes, and spam complaints.

NameTypeRequiredDescription

emailstringoptionalFilter suppressions by email address.

limitintegeroptionalMaximum number of suppression records to return per page.

pageintegeroptionalPage number for paginated results.

mailtrap_list_templates#List all email templates in the Mailtrap account.2 params▾

List all email templates in the Mailtrap account.

NameTypeRequiredDescription

limitintegeroptionalNumber of templates to return per page.

pageintegeroptionalPage number for paginated results.

mailtrap_manage_permissions#Bulk create, update, or delete resource permissions for a user or API token account access.2 params▾

Bulk create, update, or delete resource permissions for a user or API token account access.

NameTypeRequiredDescription

account_access_idintegerrequiredID of the account access record whose permissions will be updated.

permissions_jsonstringrequiredJSON string representing the full permissions payload to apply. Structure as required by the Mailtrap bulk permissions API.

mailtrap_send_domain_setup_instructions#Email DNS setup instructions for a domain to a specified recipient address.2 params▾

Email DNS setup instructions for a domain to a specified recipient address.

NameTypeRequiredDescription

domain_idintegerrequiredThe unique numeric ID of the domain whose setup instructions will be sent.

emailstringrequiredThe recipient email address to send the DNS setup instructions to.

mailtrap_track_contact_event#Submit a custom interaction event for a contact to track engagement and trigger automations.4 params▾

Submit a custom interaction event for a contact to track engagement and trigger automations.

NameTypeRequiredDescription

contact_identifierstringrequiredUUID or email address of the contact for whom the event is being tracked.

namestringrequiredName of the custom event to record, e.g. 'purchase', 'page_view', 'trial_started'.

occurred_atstringoptionalISO 8601 datetime when the event occurred. Defaults to now if omitted.

valuestringoptionalOptional value associated with the event, e.g. a purchase amount or product ID.

mailtrap_update_contact#Update a contact's custom fields, subscription status, or contact list memberships by UUID or email address.4 params▾

Update a contact's custom fields, subscription status, or contact list memberships by UUID or email address.

NameTypeRequiredDescription

contact_identifierstringrequiredUUID or email address of the contact to update. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' or 'alice@example.com'.

first_namestringoptionalNew first name for the contact.

last_namestringoptionalNew last name for the contact.

statusstringoptionalNew subscription status. Valid values: subscribed, unsubscribed.

mailtrap_update_contact_list#Update the name of an existing contact list by its ID.2 params▾

Update the name of an existing contact list by its ID.

NameTypeRequiredDescription

list_idintegerrequiredNumeric ID of the contact list to update. Example: 42.

namestringrequiredNew name for the contact list.

mailtrap_update_domain#Update domain settings such as open tracking, click tracking, and unsubscribe tracking configuration.4 params▾

Update domain settings such as open tracking, click tracking, and unsubscribe tracking configuration.

NameTypeRequiredDescription

domain_idintegerrequiredThe unique numeric ID of the domain to update.

click_trackingbooleanoptionalEnable or disable click tracking for links in emails sent from this domain.

open_trackingbooleanoptionalEnable or disable open tracking for emails sent from this domain.

unsubscribe_trackingbooleanoptionalEnable or disable unsubscribe tracking for emails sent from this domain.

mailtrap_update_template#Update an existing email template's name, subject, or body content.6 params▾

Update an existing email template's name, subject, or body content.

NameTypeRequiredDescription

email_template_idintegerrequiredID of the email template to update.

categorystringoptionalNew category for the template.

html_bodystringoptionalNew HTML body content for the email template.

namestringoptionalNew name for the email template.

subjectstringoptionalNew subject line for the email template.

text_bodystringoptionalNew plain text body content for the email template.