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 credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.

   Dashboard setup steps

   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:

• Update webhook, sandbox, project — Update an existing webhook’s URL, active state, payload format, event types, or inbound inbox scope
• Campaign start email — Start sending a draft campaign immediately
• Send email, bulk email, sandbox — Send a single transactional email via the Mailtrap Sending API (order confirmations, password resets, notifications)
• Token reset api — Expire an API token and generate a new token with the same permissions in its place
• Message reply inbound, forward sandbox — Send a reply to a received inbound email message
• List webhooks, message attachments, inboxes — List all webhooks configured for the account, including their URL, type, active state, and subscribed event types

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_batch_send_bulk_email#Send up to 500 marketing/bulk emails in a single API call via the Bulk Sending stream, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.2 params▾

Send up to 500 marketing/bulk emails in a single API call via the Bulk Sending stream, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.

NameTypeRequiredDescription

requests_jsonstringrequiredJSON array of individual email configurations (max 500), each with the same fields as a single send (from, to, subject, text/html, etc.).

base_jsonstringoptionalJSON object of base properties shared by all emails in the batch (from, subject, text, html, category, template_uuid, etc.), used as defaults when not overridden per-request.

mailtrap_batch_send_email#Send up to 500 transactional emails in a single API call, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.2 params▾

Send up to 500 transactional emails in a single API call, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.

NameTypeRequiredDescription

requests_jsonstringrequiredJSON array of individual email configurations (max 500), each with the same fields as a single send (from, to, subject, text/html, etc.).

base_jsonstringoptionalJSON object of base properties shared by all emails in the batch (from, subject, text, html, category, template_uuid, etc.), used as defaults when not overridden per-request.

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_email_campaign#Create a new email marketing campaign as a draft. Requires an existing verified sending domain (domain_id), a From local part, and a template subject. Scheduling and starting are separate actions.14 params▾

Create a new email marketing campaign as a draft. Requires an existing verified sending domain (domain_id), a From local part, and a template subject. Scheduling and starting are separate actions.

NameTypeRequiredDescription

domain_idintegerrequiredID of the verified sending domain used for the campaign.

from_local_partstringrequiredLocal part (before the @) of the From address.

namestringrequiredCampaign name.

subjectstringrequiredEmail subject line. Supports merge tags, e.g. 'Hi {{first_name}}'.

body_htmlstringoptionalHTML body of the email (the design). Optional for a draft; required before the campaign can be scheduled or started. Include an unsubscribe link via an anchor whose href contains the __unsubscribe_url__ placeholder.

body_textstringoptionalOptional plain-text alternative of the email body.

contact_list_idsstringoptionalComma-separated IDs of contact lists to send to.

contact_segment_idsstringoptionalComma-separated IDs of contact segments to send to.

delivery_modestringoptionalHow the campaign is delivered. 'rapid' sends as fast as possible; 'gradual' throttles sending to emails_per_hour.

emails_per_hourintegeroptionalDelivery throttle. Applies only when delivery_mode is 'gradual'.

from_display_namestringoptionalDisplay name shown in the From header.

reply_to_display_namestringoptionalDisplay name for the Reply-To address.

reply_to_domainstringoptionalDomain of the Reply-To address.

reply_to_local_partstringoptionalLocal part (before the @) of the Reply-To address.

mailtrap_create_inbox#Create a new inbound email inbox inside a folder. A standard inbox gets a unique generated receiving address; attaching a verified custom sending domain (with inbound enabled) instead creates a catch-all inbox that receives mail for any address on that domain.3 params▾

Create a new inbound email inbox inside a folder. A standard inbox gets a unique generated receiving address; attaching a verified custom sending domain (with inbound enabled) instead creates a catch-all inbox that receives mail for any address on that domain.

NameTypeRequiredDescription

folder_idintegerrequiredThe numeric ID of the inbound folder to create the inbox in.

namestringrequiredName for the new inbox.

domain_idintegeroptionalAttach the inbox to a verified custom sending domain (with inbound enabled), creating a catch-all inbox for any address on that domain. Omit to create a standard Mailtrap-hosted inbox. Requires the custom domains feature.

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_sub_account#Create a new sub-account under a Mailtrap organization.2 params▾

Create a new sub-account under a Mailtrap organization.

NameTypeRequiredDescription

namestringrequiredName of the new sub-account.

organization_idintegerrequiredThe numeric ID of the organization to create the sub-account under.

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_create_webhook#Create a webhook subscription that receives real-time HTTP notifications for account events (email sending, campaigns, audit log, or inbound receiving). The response includes a signing_secret returned only once — store it securely to verify payload signatures.8 params▾

Create a webhook subscription that receives real-time HTTP notifications for account events (email sending, campaigns, audit log, or inbound receiving). The response includes a signing_secret returned only once — store it securely to verify payload signatures.

NameTypeRequiredDescription

urlstringrequiredThe URL that will receive webhook payloads.

webhook_typestringrequiredThe type of webhook. Determines which events the webhook can subscribe to.

activebooleanoptionalWhether the webhook is active. Defaults to true.

domain_idintegeroptionalScopes the webhook to a specific sending domain ID, or all domains if omitted. Applicable only for email_sending and campaigns webhooks.

event_typesstringoptionalComma-separated list of event types to subscribe to. Required for email_sending and campaigns webhook types. Valid values: delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject.

inbound_inbox_idintegeroptionalID of the inbound inbox the webhook is linked to. Optional for inbound_receiving webhooks — omit to apply to all inboxes in the account. Not applicable to any other webhook type.

payload_formatstringoptionalFormat of the webhook payload. Valid values: json, jsonlines.

sending_streamstringoptionalSending stream the webhook subscribes to. Required for the email_sending webhook type. Valid values: transactional, bulk.

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_email_campaign#Soft-delete an email campaign by ID. The campaign must not be in a sending state. This action cannot be undone.1 param▾

Soft-delete an email campaign by ID. The campaign must not be in a sending state. This action cannot be undone.

NameTypeRequiredDescription

email_campaign_idintegerrequiredUnique identifier of the email campaign to permanently delete.

mailtrap_delete_project#Permanently delete a sandbox project and all of its sandbox inboxes. This action cannot be undone.1 param▾

Permanently delete a sandbox project and all of its sandbox inboxes. This action cannot be undone.

NameTypeRequiredDescription

project_idintegerrequiredThe unique numeric ID of the project to delete.

mailtrap_delete_sandbox#Permanently delete a sandbox inbox and all of its captured test messages. This action cannot be undone.1 param▾

Permanently delete a sandbox inbox and all of its captured test messages. This action cannot be undone.

NameTypeRequiredDescription

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to delete.

mailtrap_delete_sandbox_message#Permanently delete a single captured message from a sandbox inbox. This action cannot be undone.2 params▾

Permanently delete a single captured message from a sandbox inbox. This action cannot be undone.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message to delete.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

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_delete_webhook#Permanently delete a webhook by ID. This action cannot be undone.1 param▾

Permanently delete a webhook by ID. This action cannot be undone.

NameTypeRequiredDescription

webhook_idintegerrequiredThe numeric ID of the webhook to permanently delete.

mailtrap_export_contacts#Start an asynchronous export of the account's contacts to a downloadable file, optionally filtered by contact list membership or subscription status. Use the returned export ID with Get Contact Export to poll for the download URL.1 param▾

Start an asynchronous export of the account's contacts to a downloadable file, optionally filtered by contact list membership or subscription status. Use the returned export ID with Get Contact Export to poll for the download URL.

NameTypeRequiredDescription

filtersstringoptionalJSON array of filter objects to scope the export. Supported filters: {"name":"list_id","operator":"equal","value":[1,2]} and {"name":"subscription_status","operator":"equal","value":"subscribed"}. Omit to export all contacts.

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_api_token#Retrieve a single API token by ID, including its name and resource permissions. Does not return the token's secret value.1 param▾

Retrieve a single API token by ID, including its name and resource permissions. Does not return the token's secret value.

NameTypeRequiredDescription

token_idintegerrequiredID of the API token to retrieve.

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_export#Check the status of a contact export job by its ID. Returns a download URL once the export has finished.1 param▾

Check the status of a contact export job by its ID. Returns a download URL once the export has finished.

NameTypeRequiredDescription

export_idintegerrequiredThe unique numeric ID of the contact export job to check.

mailtrap_get_contact_import#Check the status and results of an asynchronous contact import job by its ID.1 param▾

Check the status and results of an asynchronous contact import job by its ID.

NameTypeRequiredDescription

import_idintegerrequiredThe unique numeric ID of the contact import job to check.

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_campaign#Retrieve a single email campaign by ID, including its state, audience, and template attributes.1 param▾

Retrieve a single email campaign by ID, including its state, audience, and template attributes.

NameTypeRequiredDescription

email_campaign_idintegerrequiredUnique identifier of the email campaign.

mailtrap_get_email_campaign_stats#Get aggregated performance metrics for a campaign: counts and rates for deliveries, opens, clicks, bounces, spam complaints, and unsubscriptions. Returns all-zero counts if the campaign has never been started. Optionally narrow the aggregation window with start_date/end_date.3 params▾

Get aggregated performance metrics for a campaign: counts and rates for deliveries, opens, clicks, bounces, spam complaints, and unsubscriptions. Returns all-zero counts if the campaign has never been started. Optionally narrow the aggregation window with start_date/end_date.

NameTypeRequiredDescription

email_campaign_idintegerrequiredUnique identifier of the email campaign.

end_datestringoptionalEnd of the aggregation window, as a date (YYYY-MM-DD).

start_datestringoptionalStart of the aggregation window, as a date (YYYY-MM-DD).

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_inbound_message#Retrieve full details of a single inbound email message, including decoded HTML/text bodies, headers, attachments with download URLs, and a link to the raw .eml file.2 params▾

Retrieve full details of a single inbound email message, including decoded HTML/text bodies, headers, attachments with download URLs, and a link to the raw .eml file.

NameTypeRequiredDescription

inbox_idintegerrequiredThe numeric ID of the inbound inbox containing the message.

message_idstringrequiredThe ID of the inbound message to retrieve.

mailtrap_get_inbox#Retrieve a single inbound email inbox by ID, including its receiving address and attached domain.2 params▾

Retrieve a single inbound email inbox by ID, including its receiving address and attached domain.

NameTypeRequiredDescription

folder_idintegerrequiredThe numeric ID of the inbound folder that contains the inbox.

inbox_idintegerrequiredThe numeric ID of the inbox to retrieve.

mailtrap_get_message_attachment#Get metadata for a single attachment captured on a sandbox test message, including filename, content type, and size.3 params▾

Get metadata for a single attachment captured on a sandbox test message, including filename, content type, and size.

NameTypeRequiredDescription

attachment_idintegerrequiredThe numeric ID of the attachment to retrieve.

message_idintegerrequiredThe numeric ID of the sandbox message that owns the attachment.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

mailtrap_get_message_body_html#Get the rendered HTML body content of a captured sandbox test message.2 params▾

Get the rendered HTML body content of a captured sandbox test message.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message whose HTML body will be retrieved.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

mailtrap_get_message_body_text#Get the plain-text body content of a captured sandbox test message.2 params▾

Get the plain-text body content of a captured sandbox test message.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message whose text body will be retrieved.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

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_project#Get details of a single sandbox project by ID, including its sandbox inboxes.1 param▾

Get details of a single sandbox project by ID, including its sandbox inboxes.

NameTypeRequiredDescription

project_idintegerrequiredThe unique numeric ID of the project to retrieve.

mailtrap_get_sandbox#Get details of a single sandbox inbox by ID, including its email address and credentials info.1 param▾

Get details of a single sandbox inbox by ID, including its email address and credentials info.

NameTypeRequiredDescription

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to retrieve.

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_get_webhook#Retrieve a single webhook by its ID, including its URL, type, active state, and subscribed event types.1 param▾

Retrieve a single webhook by its ID, including its URL, type, active state, and subscribed event types.

NameTypeRequiredDescription

webhook_idintegerrequiredThe numeric ID of the webhook to retrieve.

mailtrap_import_contacts#Bulk import up to 50,000 contacts in a single request, with support for custom fields and list assignment. Contacts with matching email addresses are updated automatically. The import runs asynchronously — use the returned import ID with Get Contact Import to check status and results.1 param▾

Bulk import up to 50,000 contacts in a single request, with support for custom fields and list assignment. Contacts with matching email addresses are updated automatically. The import runs asynchronously — use the returned import ID with Get Contact Import to check status and results.

NameTypeRequiredDescription

contactsstringrequiredJSON array of contact objects to import (up to 50,000). Each needs email, and may include fields (custom field key-value map), list_ids_included, and list_ids_excluded.

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_campaigns#Returns a paginated list of the account's email marketing campaigns, newest first. Supports searching by name.3 params▾

Returns a paginated list of the account's email marketing campaigns, newest first. Supports searching by name.

NameTypeRequiredDescription

per_pageintegeroptionalNumber of campaigns per page. Defaults to 50, maximum 100.

searchstringoptionalSearch string to filter campaigns by name.

tokenintegeroptionalPage number to retrieve (page-token pagination). Defaults to 1.

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_inbound_messages#List real inbound email messages received by an inbox, newest first, within the account's retention window. Supports cursor-based pagination via last_id.2 params▾

List real inbound email messages received by an inbox, newest first, within the account's retention window. Supports cursor-based pagination via last_id.

NameTypeRequiredDescription

inbox_idintegerrequiredThe numeric ID of the inbound inbox to list messages from.

last_idstringoptionalCursor for pagination. Pass the previous response's last_id value to fetch the next page.

mailtrap_list_inboxes#List all inbound email inboxes in a folder. Inbound inboxes receive real email at a generated or custom-domain address, distinct from the Email Testing sandboxes used for capturing outgoing test messages.1 param▾

List all inbound email inboxes in a folder. Inbound inboxes receive real email at a generated or custom-domain address, distinct from the Email Testing sandboxes used for capturing outgoing test messages.

NameTypeRequiredDescription

folder_idintegerrequiredThe numeric ID of the inbound folder that contains the inboxes.

mailtrap_list_message_attachments#List the attachments captured on a sandbox test message, including filename, content type, and size.2 params▾

List the attachments captured on a sandbox test message, including filename, content type, and size.

NameTypeRequiredDescription

message_idintegerrequiredThe numeric ID of the sandbox message whose attachments will be listed.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox containing the message.

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_list_webhooks#List all webhooks configured for the account, including their URL, type, active state, and subscribed event types.0 params▾

List all webhooks configured for the account, including their URL, type, active state, and subscribed event types.

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_reply_inbound_message#Send a reply to a received inbound email message. Must include text and/or html. Recipients default to the original sender's reply-to/from address when to_json is omitted. The from address is rejected for standard Mailtrap-hosted inboxes and required only for custom-domain inboxes.13 params▾

Send a reply to a received inbound email message. Must include text and/or html. Recipients default to the original sender's reply-to/from address when to_json is omitted. The from address is rejected for standard Mailtrap-hosted inboxes and required only for custom-domain inboxes.

NameTypeRequiredDescription

inbox_idintegerrequiredThe numeric ID of the inbound inbox containing the message.

message_idstringrequiredThe ID of the inbound message to reply to.

attachments_jsonstringoptionalJSON array of attachment objects, e.g. '[{"filename":"invoice.pdf","content":"<base64>","type":"application/pdf"}]'. content must be base64-encoded.

bcc_jsonstringoptionalJSON array of BCC recipient objects, same format as to_json.

categorystringoptionalEmail API category label for the sent reply, used for grouping in delivery statistics.

cc_jsonstringoptionalJSON array of CC recipient objects, same format as to_json.

custom_variables_jsonstringoptionalJSON object of custom key-value metadata to attach to the reply, e.g. '{"ticket_id":"12345"}'.

from_emailstringoptionalSender email address. Rejected for standard Mailtrap-hosted inboxes; required for custom-domain inboxes, where it must belong to the inbox's domain.

from_namestringoptionalSender display name. Only used together with from_email.

headers_jsonstringoptionalJSON object of additional email headers to send, e.g. '{"X-Priority":"1"}'.

htmlstringoptionalHTML reply body. At least one of text or html is required.

textstringoptionalPlain-text reply body. At least one of text or html is required.

to_jsonstringoptionalJSON array of recipient objects, e.g. '[{"email":"jane@example.com","name":"Jane"}]'. Defaults to the original sender's reply-to/from address if omitted.

mailtrap_reset_api_token#Expire an API token and generate a new token with the same permissions in its place. The old token keeps working for a short grace period. The response includes the new secret value once — store it securely. Only tokens that have not already been reset can be reset.1 param▾

Expire an API token and generate a new token with the same permissions in its place. The old token keeps working for a short grace period. The response includes the new secret value once — store it securely. Only tokens that have not already been reset can be reset.

NameTypeRequiredDescription

token_idintegerrequiredID of the API token to reset.

mailtrap_sandbox_batch_send_email#Send up to 500 test emails into a Mailtrap sandbox inbox in a single API call, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.3 params▾

Send up to 500 test emails into a Mailtrap sandbox inbox in a single API call, each with its own recipients and content, optionally sharing base properties. Returns HTTP 200 even if individual messages fail -- check the per-message results for status.

NameTypeRequiredDescription

requests_jsonstringrequiredJSON array of individual email configurations (max 500), each with the same fields as a single send (from, to, subject, text/html, etc.).

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to deliver the test emails into.

base_jsonstringoptionalJSON object of base properties shared by all emails in the batch (from, subject, text, html, template_uuid, etc.), used as defaults when not overridden per-request.

mailtrap_sandbox_send_email#Send a test email directly into a Mailtrap sandbox inbox via the Sandbox Sending API, for testing your email content without delivering to a real recipient. Provide text and/or html content, or a template_uuid.10 params▾

Send a test email directly into a Mailtrap sandbox inbox via the Sandbox Sending API, for testing your email content without delivering to a real recipient. Provide text and/or html content, or a template_uuid.

NameTypeRequiredDescription

from_emailstringrequiredSender email address for the test email.

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to deliver the test email into.

to_jsonstringrequiredJSON array of recipient objects, e.g. '[{"email":"user@example.com","name":"Test User"}]'.

attachments_jsonstringoptionalJSON array of attachment objects. content must be base64-encoded.

from_namestringoptionalSender display name.

htmlstringoptionalHTML email body. At least one of text or html is required unless template_uuid is set.

subjectstringoptionalEmail subject line. Required unless sending from a template that provides its own subject.

template_uuidstringoptionalUUID of a saved Mailtrap template to send from, instead of subject/text/html.

template_variables_jsonstringoptionalJSON object of variable values to substitute into the template.

textstringoptionalPlain-text email body. At least one of text or html is required unless template_uuid is set.

mailtrap_send_bulk_email#Send a marketing or newsletter email via the Mailtrap Bulk Sending stream, optimized for high-volume, non-transactional sends. Provide text and/or html content, or a template_uuid to send from a saved template.15 params▾

Send a marketing or newsletter email via the Mailtrap Bulk Sending stream, optimized for high-volume, non-transactional sends. Provide text and/or html content, or a template_uuid to send from a saved template.

NameTypeRequiredDescription

from_emailstringrequiredSender email address. Must be on a verified sending domain.

to_jsonstringrequiredJSON array of recipient objects, e.g. '[{"email":"jane@example.com","name":"Jane"}]'.

attachments_jsonstringoptionalJSON array of attachment objects, e.g. '[{"filename":"flyer.pdf","content":"<base64>","type":"application/pdf"}]'. content must be base64-encoded.

bcc_jsonstringoptionalJSON array of BCC recipient objects, same format as to_json.

categorystringoptionalCategory label for grouping this email in Mailtrap statistics.

cc_jsonstringoptionalJSON array of CC recipient objects, same format as to_json.

custom_variables_jsonstringoptionalJSON object of custom key-value metadata to attach to the email, e.g. '{"campaign_id":"42"}'.

from_namestringoptionalSender display name.

headers_jsonstringoptionalJSON object of additional email headers to send, e.g. '{"List-Unsubscribe":"<mailto:unsub@example.com>"}'.

htmlstringoptionalHTML email body. At least one of text or html is required unless template_uuid is set.

reply_to_emailstringoptionalReply-to email address.

subjectstringoptionalEmail subject line. Required unless sending from a template that provides its own subject.

template_uuidstringoptionalUUID of a saved Mailtrap template to send from, instead of subject/text/html.

template_variables_jsonstringoptionalJSON object of variable values to substitute into the template, e.g. '{"first_name":"Jane"}'.

textstringoptionalPlain-text email body. At least one of text or html is required unless template_uuid is set.

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_send_email#Send a single transactional email via the Mailtrap Sending API (order confirmations, password resets, notifications). Provide text and/or html content, or a template_uuid to send from a saved template.15 params▾

Send a single transactional email via the Mailtrap Sending API (order confirmations, password resets, notifications). Provide text and/or html content, or a template_uuid to send from a saved template.

NameTypeRequiredDescription

from_emailstringrequiredSender email address. Must be on a verified sending domain.

to_jsonstringrequiredJSON array of recipient objects, e.g. '[{"email":"jane@example.com","name":"Jane"}]'.

attachments_jsonstringoptionalJSON array of attachment objects, e.g. '[{"filename":"invoice.pdf","content":"<base64>","type":"application/pdf"}]'. content must be base64-encoded.

bcc_jsonstringoptionalJSON array of BCC recipient objects, same format as to_json.

categorystringoptionalCategory label for grouping this email in Mailtrap statistics.

cc_jsonstringoptionalJSON array of CC recipient objects, same format as to_json.

custom_variables_jsonstringoptionalJSON object of custom key-value metadata to attach to the email, e.g. '{"user_id":"42"}'.

from_namestringoptionalSender display name.

headers_jsonstringoptionalJSON object of additional email headers to send, e.g. '{"X-Priority":"1"}'.

htmlstringoptionalHTML email body. At least one of text or html is required unless template_uuid is set.

reply_to_emailstringoptionalReply-to email address.

subjectstringoptionalEmail subject line. Required unless sending from a template that provides its own subject.

template_uuidstringoptionalUUID of a saved Mailtrap template to send from, instead of subject/text/html.

template_variables_jsonstringoptionalJSON object of variable values to substitute into the template, e.g. '{"order_id":"1234"}'.

textstringoptionalPlain-text email body. At least one of text or html is required unless template_uuid is set.

mailtrap_start_email_campaign#Start sending a draft campaign immediately. Runs full sending validation (template design, audience, verified domain, billing limits); on failure the campaign stays a draft and the request fails. The campaign must be in the draft state.1 param▾

Start sending a draft campaign immediately. Runs full sending validation (template design, audience, verified domain, billing limits); on failure the campaign stays a draft and the request fails. The campaign must be in the draft state.

NameTypeRequiredDescription

email_campaign_idintegerrequiredUnique identifier of the draft email campaign to start sending.

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_email_campaign#Update an existing draft email campaign. Only the provided attributes are changed; the template (subject/design) is always edited in place. Only draft campaigns can be updated — editing a scheduled or sending campaign fails.15 params▾

Update an existing draft email campaign. Only the provided attributes are changed; the template (subject/design) is always edited in place. Only draft campaigns can be updated — editing a scheduled or sending campaign fails.

NameTypeRequiredDescription

email_campaign_idintegerrequiredUnique identifier of the draft email campaign to update.

body_htmlstringoptionalHTML body of the email (the design). Required before the campaign can be scheduled or started.

body_textstringoptionalPlain-text alternative of the email body.

contact_list_idsstringoptionalComma-separated IDs of contact lists to send to. Replaces the campaign's full set of included lists.

contact_segment_idsstringoptionalComma-separated IDs of contact segments to send to. Replaces the campaign's full set of included segments.

delivery_modestringoptionalHow the campaign is delivered. 'rapid' sends as fast as possible; 'gradual' throttles sending to emails_per_hour.

domain_idintegeroptionalID of the verified sending domain used for the campaign.

emails_per_hourintegeroptionalDelivery throttle. Applies only when delivery_mode is 'gradual'.

from_display_namestringoptionalDisplay name shown in the From header.

from_local_partstringoptionalLocal part (before the @) of the From address.

namestringoptionalNew campaign name.

reply_to_display_namestringoptionalDisplay name for the Reply-To address.

reply_to_domainstringoptionalDomain of the Reply-To address.

reply_to_local_partstringoptionalLocal part (before the @) of the Reply-To address.

subjectstringoptionalEmail subject line. Supports merge tags, e.g. 'Hi {{first_name}}'.

mailtrap_update_project#Rename an existing sandbox project.2 params▾

Rename an existing sandbox project.

NameTypeRequiredDescription

namestringrequiredNew name for the project.

project_idintegerrequiredThe unique numeric ID of the project to update.

mailtrap_update_sandbox#Rename a sandbox inbox or change its email username.3 params▾

Rename a sandbox inbox or change its email username.

NameTypeRequiredDescription

sandbox_idintegerrequiredThe numeric ID of the sandbox inbox to update.

email_usernamestringoptionalNew local-part username for the sandbox inbox's email address.

namestringoptionalNew display name for the sandbox inbox.

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.

mailtrap_update_webhook#Update an existing webhook's URL, active state, payload format, event types, or inbound inbox scope. Only the fields provided are changed.6 params▾

Update an existing webhook's URL, active state, payload format, event types, or inbound inbox scope. Only the fields provided are changed.

NameTypeRequiredDescription

webhook_idintegerrequiredThe numeric ID of the webhook to update.

activebooleanoptionalWhether the webhook is active.

event_typesstringoptionalComma-separated list of event types to subscribe to. Applicable only for email_sending and campaigns webhooks. Valid values: delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject.

inbound_inbox_idintegeroptionalID of the inbound inbox the webhook is linked to. Applicable only for inbound_receiving webhooks.

payload_formatstringoptionalFormat of the webhook payload. Valid values: json, jsonlines.

urlstringoptionalNew URL that will receive webhook payloads.