List SMTP Configurations

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 managing outbound email need to inspect which SMTP configurations are active for an organization — for example, to verify which server is currently set as the default, or to audit all configurations before making changes. This use case shows how to list SMTP configurations using the Pipefy GraphQL API in two scenarios:

All configurations: retrieve every SMTP configuration for the organization.
Default configuration only: filter results to the configuration flagged as defaultSmtp.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Your token must have Admin permissions on the organization. Users without manage access to SMTP configurations receive an empty result set.
Organization ID: Identify the Organization whose SMTP configurations you want to list.

Find Your Organization ID

Open the Organization in your browser.
The URL will include the Organization ID: https://app.pipefy.com/organizations/123456789.
Organization ID = 123456789 (the number after /organizations/).

Scenario A: List all SMTP configurations

Retrieve every SMTP configuration that belongs to an organization.

Operation

{
  smtpConfigurations(organizationId: "980700673") {
    nodes {
      id
      host
      port
      username
      defaultSmtp
      organizationId
    }
  }
}

Arguments

organizationId: ID — Required — the ID of the organization whose configurations to list.
defaultSmtp: Boolean — Optional — when provided, filters results to configurations where defaultSmtp matches the given value. Omit to return all configurations.

Expected response

{
  "data": {
    "smtpConfigurations": {
      "nodes": [
        {
          "id": "060f4d01-b412-43e0-999c-73e4f36889a9",
          "host": "smtp.sendgrid.net",
          "port": "587",
          "username": "[email protected]",
          "defaultSmtp": true,
          "organizationId": "980700673"
        },
        {
          "id": "b6a2f6e0-1d4c-4a1a-9e3e-2a1a0c5b9b23",
          "host": "smtp.mailgun.org",
          "port": "465",
          "username": "[email protected]",
          "defaultSmtp": false,
          "organizationId": "980700673"
        }
      ]
    }
  }
}

Scenario B: Retrieve the default SMTP configuration

Pass defaultSmtp: true to return only the configuration currently set as the organization default.

Operation

{
  smtpConfigurations(organizationId: "980700673", defaultSmtp: true) {
    nodes {
      id
      host
      port
      defaultSmtp
      organizationId
    }
  }
}

Arguments

organizationId: ID — Required — the ID of the organization.
defaultSmtp: Boolean — true — filters to the single configuration marked as the organization default.

Expected response

{
  "data": {
    "smtpConfigurations": {
      "nodes": [
        {
          "id": "060f4d01-b412-43e0-999c-73e4f36889a9",
          "host": "smtp.sendgrid.net",
          "port": "587",
          "defaultSmtp": true,
          "organizationId": "980700673"
        }
      ]
    }
  }
}

Key notes

Results are paginated — the query returns up to 50 configurations per page. If you need to paginate, use the standard connection fields (pageInfo { hasNextPage endCursor }) alongside nodes.
Only users with Admin (manage) access to SMTP configurations for the organization receive records. A valid organization membership without manage access returns an empty nodes array, not an error.
Querying an organization you do not belong to returns a GraphQL error, not an empty result.
port is returned as a String, not an integer, even though SMTP ports are numeric.
Only one configuration can be marked defaultSmtp: true per organization at a time.
To create or update SMTP configurations, see Create SMTP Configuration.