Set the Default Organization 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

When an organization has several SMTP Custom Emails, one of them can be promoted to the organization-wide default sender. The default sender is used for outbound messages when no specific sender is selected, and it is returned first by the List SMTP Custom Emails query.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Your token must be able to update the target organization.
An SMTP Custom Email: The custom email must belong to an SMTP configuration of the same organization.
IDs: See our Get resource IDs page for how to find the organizationId. Use List SMTP Custom Emails to find the smtpCustomEmailId.

Step 1: Run the mutation

mutation SetDefaultOrganizationSmtpCustomEmail(
  $organizationId: ID!
  $smtpCustomEmailId: ID
) {
  setDefaultOrganizationSmtpCustomEmail(
    input: {
      organizationId: $organizationId
      smtpCustomEmailId: $smtpCustomEmailId
    }
  ) {
    smtpCustomEmail {
      id
      emailAddress
      senderName
    }
  }
}

Variables

{
  "organizationId": "12345",
  "smtpCustomEmailId": "678"
}

Step 2: Check the response

{
  "data": {
    "setDefaultOrganizationSmtpCustomEmail": {
      "smtpCustomEmail": {
        "id": 678,
        "emailAddress": "[email protected]",
        "senderName": "Your Company"
      }
    }
  }
}

Returned fields

Field	Description
`smtpCustomEmail.id`	The ID of the custom email now set as the organization default (`null` when the default was cleared)
`smtpCustomEmail.emailAddress`	The sender email address of the new default
`smtpCustomEmail.senderName`	The display name shown to recipients

Removing the default sender

Pass smtpCustomEmailId: null (or omit it) to clear the organization's default sender:

{
  "organizationId": "12345",
  "smtpCustomEmailId": null
}

The response returns "smtpCustomEmail": null, confirming no default sender is set.

Implementation notes

The custom email must be configured for the given organization. Passing an email that belongs to another organization returns an invalid input error.
Only users who can update the organization may change its default sender.