Mail (SMTP)

Connect an SMTP server to Squid to send email from AI agents and backend code

The Mail connector's functionality

The Mail connector lets your Squid application send email through any SMTP server:

• AI agents connected to the Mail connector can compose and send emails on the user's behalf — for example, "Email the report to the team."
• Backend code can send emails programmatically, including emails with attachments.

The connector works with any standard SMTP provider. Throttling and sending quotas are governed by your SMTP provider.

Adding the Mail connector to your Squid application

1. Navigate to the Connectors tab in the Squid Console.

2. Click Available Connectors.

3. Find the Mail connector, and select Add Connector.

4. Provide the following configuration details:

Connector ID: A string that uniquely identifies the connector in your code.

SMTP Host: The hostname of your SMTP server, such as smtp.example.com. Do not include a protocol prefix.

SMTP Port: The port number for your SMTP server, such as 25, 465, or 587.

SMTP Username: The username to authenticate with the SMTP server.

SMTP Password: The password to authenticate with the SMTP server. The password is stored securely as a Squid secret. If your email provider uses app-specific passwords, use one here.

SMTP Encryption: The encryption method to use when connecting to the SMTP server: tls (default), ssl, or none.

SMTP From Address: The email address that appears as the sender when a send request doesn't specify one.

Using the Mail connector in your application

No-code Studio

1. Navigate to the Studio tab in the Squid Console.

2. Click Create AI Agent.

3. Provide an agent ID and description, such as "assistant-agent" and "This agent can send emails on the user's behalf".

4. Click Add Abilities.

5. Expand the Mail entry and select the Mail connector you created earlier.

6. Give a description for how the agent should use this connection, such as "Call this when the user asks to send an email."

7. Click on Test and try asking the agent to send a test email to yourself.

Using the Squid SDK

If you are creating your AI agent with the Squid SDK, connect the Mail connector by adding it to the connectedIntegrations option of the ask() function:

TypeScript

await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('Send a summary of this conversation to team@example.com', {
    connectedIntegrations: [
      {
        integrationId: 'MAIL_CONNECTOR_ID',
        integrationType: 'mail',
        description: 'Call this connector to send emails',
      },
    ],
  });

Python

await squid.ai().agent('AGENT_ID').ask(
    'Send a summary of this conversation to team@example.com',
    options={
        'connectedIntegrations': [
            {
                'integrationId': 'MAIL_CONNECTOR_ID',
                'integrationType': 'mail',
                'description': 'Call this connector to send emails',
            }
        ]
    },
)

Sending email from backend code

For programmatic sending — including attachments, which are not available through the AI agent tool — install the @squidcloud/mail-client package and call it from your Squid backend:

npm install @squidcloud/mail-client

import { SquidMailClient } from '@squidcloud/mail-client';

const mail = new SquidMailClient(this.squid);

await mail.sendMail({
  integrationId: 'MAIL_CONNECTOR_ID',
  to: 'recipient@example.com',
  subject: 'Monthly report',
  body: '<h1>Report</h1><p>See the attached PDF.</p>',
  html: true,
  attachments: [
    {
      filename: 'report.pdf',
      content: base64EncodedPdf,
      encoding: 'base64',
    },
  ],
});

If from is omitted from the request, the connector uses the configured SMTP From Address. Each attachment provides either inline content or a path to a file on the backend, but not both.

note

Sending mail requires a privileged backend context, such as an executable, scheduler, or trigger. Unauthenticated client-side calls are rejected.