Update SMTP Configuration

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 occasionally need to change how Pipefy connects to their SMTP server — for example, rotating credentials, pointing to a new host or port, or promoting a configuration to be the organization default. This use case shows how to update an existing SMTP configuration using the Pipefy GraphQL API.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must have Admin (manage) access to SMTP configurations for the organization. Users without manage access receive a permission error.
3. SMTP Configuration ID: Identify the configuration you want to update — see List SMTP Configurations to retrieve existing IDs.

Step 1: Update the configuration

Provide the id of the configuration plus any fields you want to change. All fields except id are optional — send only the ones you want to modify.

Operation

mutation UpdateSmtpConfig($input: UpdateSmtpConfigurationInput!) {
  updateSmtpConfiguration(input: $input) {
    smtpConfiguration {
      id
      host
      port
      username
      defaultSmtp
      organizationId
    }
  }
}

Arguments (input)

• id: ID — Required — the ID of the SMTP configuration to update.
• host: String — Optional — SMTP server host.
• port: Int — Optional — SMTP port (e.g., 587).
• username: String — Optional — SMTP username.
• password: String — Optional — SMTP password. Omit or send null to keep the current password unchanged.
• defaultSmtp: Boolean — Optional — set to true to make this the organization's default configuration.

Example (realistic values)

{
  "input": {
    "id": "060f4d01-b412-43e0-999c-73e4f36889a9",
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "[email protected]",
    "defaultSmtp": true
  }
}

Expected response

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

Key notes

• Sending password: null (or omitting it) leaves the stored password unchanged — useful when updating other fields without re-sending credentials.
• Only one configuration can be marked defaultSmtp: true per organization at a time. Promoting a configuration to default while another default already exists returns a validation error (Default smtp has already been taken).
• port is returned as a String, not an integer, even though SMTP ports are numeric.
• Updating a configuration you do not have manage access to returns a permission error.
• Requesting an id that does not exist returns a not-found error.
• To create a configuration, see Create SMTP Configuration. To remove one, see Delete SMTP Configuration.