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

Create SMTP Custom Email with SMTP Configuration

Create a sender (SMTP Custom Email) alongside its SMTP configuration via the Internal GraphQL API.

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

Many teams need to onboard a custom sender for outbound emails and configure the SMTP settings at the same time. This mutation creates both the SmtpCustomEmail and the associated SmtpConfiguration in a single operation. It supports both credential-based SMTP and IP relay (no 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. Operation overview

mutation CreateSmtpCustomEmailWithConfiguration(
  $senderName: String!
  $emailAddress: String!
  $smtpConfiguration: SmtpConfigurationInput
) {
  createSmtpCustomEmailWithConfiguration(
    input: {
      senderName: $senderName
      emailAddress: $emailAddress
      smtpConfiguration: $smtpConfiguration
    }
  ) {
    smtpCustomEmail {
      id
      emailAddress
      senderName
      smtpConfiguration {
        id
        host
        port
        organizationId
        ipRelayAuth
      }
    }
  }
}

Arguments

  • senderName: String — Required — Friendly display name for the sender.
  • emailAddress: String — Required — The email address for the sender.
  • smtpConfiguration: SmtpConfigurationInput — SMTP settings for this sender:
    • host: String — Required — SMTP server host.
    • port: Int — Required — SMTP server port.
    • organizationId: ID — Required — Target organization.
    • ipRelayAuth: Boolean (default: false) — Enable IP relay (no credentials).
    • username: String — Required if ipRelayAuth is false.
    • password: String — Required if ipRelayAuth is false.

3. Scenario A: Credentials-based SMTP

Use this when your SMTP requires authentication.

Example variables

{
  "senderName": "Acme Support",
  "emailAddress": "[email protected]",
  "smtpConfiguration": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "organizationId": "980700673",
    "username": "[email protected]",
    "password": "s3cr3t-PA"
  }
}

Expected response

{
  "data": {
    "createSmtpCustomEmailWithConfiguration": {
      "smtpCustomEmail": {
        "id": "a4f1b2c3-d4e5-6f78-9abc-d0e1f2a3b4c5",
        "emailAddress": "[email protected]",
        "senderName": "Acme Support",
        "smtpConfiguration": {
          "id": "7e9f4d01-b412-43e0-999c-73e4f36889a9",
          "host": "smtp.sendgrid.net",
          "port": "587",
          "organizationId": "980700673",
          "ipRelayAuth": false
        }
      }
    }
  }
}

4. Scenario B: IP relay (no credentials)

Use this when your infrastructure authenticates by source IP and credentials are not required.

Example variables

{
  "senderName": "Acme Notifications",
  "emailAddress": "[email protected]",
  "smtpConfiguration": {
    "host": "relay.acme.internal",
    "port": 25,
    "organizationId": "980700673",
    "ipRelayAuth": true
  }
}

Expected response

{
  "data": {
    "createSmtpCustomEmailWithConfiguration": {
      "smtpCustomEmail": {
        "id": "c9a2f6e0-1d4c-4a1a-9e3e-2a1a0c5b9b23",
        "emailAddress": "[email protected]",
        "senderName": "Acme Notifications",
        "smtpConfiguration": {
          "id": "3b1a2c3d-4e5f-6789-0abc-def123456789",
          "host": "relay.acme.internal",
          "port": "25",
          "organizationId": "980700673",
          "ipRelayAuth": true
        }
      }
    }
  }
}

Key notes

  • When ipRelayAuth is omitted, it defaults to false, and credentials are required.
  • The email address must be unique within the organization.
  • This mutation creates both the custom sender and its SMTP configuration together, simplifying provisioning.