Update an SMTP Custom Email

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

Use this mutation to change a sender's display name or email address, and optionally update the SMTP configuration attached to it. When you omit smtpConfiguration, the sender is reassigned to the organization's default SMTP configuration.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must be able to manage the target SMTP custom email.
3. SMTP Custom Email ID: Identify the id of the sender you want to update.

Step 1: Run the mutation

mutation UpdateSmtpCustomEmail(
  $id: ID!
  $senderName: String
  $emailAddress: String
  $smtpConfiguration: SmtpConfigurationInput
) {
  updateSmtpCustomEmail(
    input: {
      id: $id
      senderName: $senderName
      emailAddress: $emailAddress
      smtpConfiguration: $smtpConfiguration
    }
  ) {
    smtpCustomEmail {
      id
      emailAddress
      senderName
      smtpConfigurationId
      smtpConfiguration {
        id
        host
        port
        organizationId
      }
    }
  }
}

Arguments

• id: ID — Required — The SMTP Custom Email to update.
• senderName: String — Optional — New display name for the sender.
• emailAddress: String — Optional — New email address for the sender.
• smtpConfiguration: SmtpConfigurationInput — Optional — SMTP settings to update on the attached configuration:
  • host: String — SMTP server host.
  • port: Int — SMTP server port.
  • organizationId: ID — Target organization.
  • username: String — SMTP username.
  • password: String — SMTP password. Omit to keep the current password.

When smtpConfiguration is omitted, the sender is reassigned to the organization's default SMTP configuration, and its previous (non-default) configuration is removed.

Example variables

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

Expected response

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

Key notes

• Omit password inside smtpConfiguration to keep the existing password unchanged.
• Omitting smtpConfiguration entirely reassigns the sender to the organization's default SMTP configuration.
• Passing an id that does not exist returns a "not found" error.