Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Mailtrap

Scalekit connector
Open markdown

The Mailtrap connector lets your AI agent act in each user's Mailtrap account. Each user connects their own Mailtrap access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 92 tools.

Tools
92
What they doRead · write · destructive
44 · 35 · 1344 read35 write13 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  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. Create the Mailtrap connection

    In AgentKit > Connections, create a Mailtrap connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    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.

    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.

      Mailtrap API Tokens settings page showing an existing token and the Add Token button

    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 one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

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

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { ConnectorStatus } from '@scalekit-sdk/node'
      

      const authorizationDetails = {
        details: {
          case: 'staticAuth',
          value: { details: { token: 'your-mailtrap-api-token' } },
        },
      }
      

      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
        connectionName: 'mailtrap',
        identifier: 'user_123',
        authorizationDetails,
      })
      

      // Make sure the account is ACTIVE before the first tool call.
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
        ;({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
          connectionName: 'mailtrap',
          identifier: 'user_123',
          authorizationDetails,
        }))
      }

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'mailtrap'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Mailtrap:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'mailtrap_get_accounts',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Mailtrap credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • mailtrap_get_accountsList all Mailtrap accounts the API token has access to.Read-only

    Get Accounts

    List all Mailtrap accounts the API token has access to.

    Inputs

    This tool takes no inputs.

  • mailtrap_get_api_tokenRetrieve a single API token by ID, including its name and resource permissions.Read-only

    Get API Token

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

    Inputs

    token_idintegerrequired
    ID of the API token to retrieve.
  • mailtrap_get_billing_usageGet current billing cycle usage for Sandbox, Email API, and Email Marketing quotas.Read-only

    Get Billing Usage

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

    Inputs

    This tool takes no inputs.

  • mailtrap_get_contactRetrieve a contact by UUID or email address, including their subscription status and custom fields.Read-only

    Get Contact

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

    Inputs

    contact_identifierstringrequired
    UUID or email address of the contact to retrieve. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' or 'alice@example.com'.
  • mailtrap_get_contact_exportCheck the status of a contact export job by its ID.Read-only

    Get Contact Export

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

    Inputs

    export_idintegerrequired
    The unique numeric ID of the contact export job to check.
  • mailtrap_get_contact_importCheck the status and results of an asynchronous contact import job by its ID.Read-only

    Get Contact Import

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

    Inputs

    import_idintegerrequired
    The unique numeric ID of the contact import job to check.
  • mailtrap_get_contact_listGet details of a specific contact list by ID, including its name and contact count.Read-only

    Get Contact List

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

    Inputs

    list_idintegerrequired
    Numeric ID of the contact list to retrieve. Example: 42.
  • mailtrap_get_domainGet details for a specific sending domain including DNS records, DKIM keys, and verification status.Read-only

    Get Domain

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

    Inputs

    domain_idintegerrequired
    ID of the sending domain to retrieve.
All 73 in Communication