API Reference
Support from Community ↗︎Back to Pipefy ↗︎

Create SMTP Configuration

Create an SMTP configuration via the Internal GraphQL API, with or without IP relay credentials.

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Why this use case

Teams often need to configure how Pipefy sends outbound emails from an organization. This use case shows how to create an SMTP configuration using the Internal GraphQL API in two scenarios:

  • Credentials-based (default): provide username and password.
  • IP relay (no credentials): set ipRelayAuth to true and omit credentials.

Prerequisites

  1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).

  2. Permissions: Ensure your token has the necessary permissions.

  3. Organization ID: Identify the Organization where the STMP configuration will be created.

Step 1: Find Your Organization ID

1. Via Pipefy UI

2. Scenario A: Create SMTP configuration with credentials (default)

When ipRelayAuth is not provided (defaults to false), username and password are required.

Operation

mutation CreateSmtpConfig($input: CreateSmtpConfigurationInput!) {
  createSmtpConfiguration(input: $input) {
    smtpConfiguration {
      id
      host
      port
      username
      encryptedPassword
      defaultSmtp
      organizationId
      outlookIntegration
    }
  }
}

Arguments (input)

  • host: String — Required — SMTP server host
  • port: Int — Required — SMTP port (e.g., 587)
  • organizationId: ID — Required — target organization
  • defaultSmtp: Boolean — Required — whether this should be the organization’s default SMTP
  • username: String — Required — SMTP username
  • password: String — Required — SMTP password

Example (realistic values)

{
  "input": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "organizationId": "980700673",
    "defaultSmtp": false,
    "username": "[email protected]",
    "password": "s3cr3t-PA"
  }
}

Expected response

{
  "data": {
    "createSmtpConfiguration": {
      "smtpConfiguration": {
        "id": "060f4d01-b412-43e0-999c-73e4f36889a9",
        "host": "smtp.sendgrid.net",
        "port": "587",
        "username": "[email protected]",
        "encryptedPassword": "********",
        "defaultSmtp": false,
        "organizationId": "980700673",
        "outlookIntegration": false
      }
    }
  }
}

3. Scenario B: Create SMTP configuration using IP relay (no credentials)

Set ipRelayAuth to true and omit username and password. This is useful when your infrastructure authenticates by source IP.

Operation

You can reuse the same mutation. For IP relay, you don’t need to request fields like username in the selection set.

mutation CreateSmtpConfig($input: CreateSmtpConfigurationInput!) {
  createSmtpConfiguration(input: $input) {
    smtpConfiguration {
      id
      host
      port
      defaultSmtp
      organizationId
    }
  }
}

Arguments (input)

  • host: String — Required — SMTP or relay host (e.g., internal relay)
  • port: Int — Required — SMTP port (often 25 for relay)
  • organizationId: ID — Required — target organization
  • defaultSmtp: Boolean — Required — whether this should be the organization’s default SMTP
  • ipRelayAuth: Boolean — set to true to enable IP-based relay (no credentials)

Example (realistic values)

{
  "input": {
    "host": "relay.acme.internal",
    "port": 25,
    "organizationId": "980700673",
    "defaultSmtp": true,
    "ipRelayAuth": true
  }
}

Expected response

{
  "data": {
    "createSmtpConfiguration": {
      "smtpConfiguration": {
        "id": "b6a2f6e0-1d4c-4a1a-9e3e-2a1a0c5b9b23",
        "host": "relay.acme.internal",
        "port": "25",
        "defaultSmtp": true,
        "organizationId": "980700673"
      }
    }
  }
}

Key notes

  • If ipRelayAuth is omitted, it defaults to false and credentials are required.
  • Only one configuration can be marked as defaultSmtp per organization at a time.
  • Use the internal GraphiQL UI at http://localhost:3000/graphiql_internal or send requests to POST /internal_api with an authenticated session.