List SMTP Custom Emails

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 query to list the custom senders available in an organization — for example to populate a sender picker or to audit the senders attached to each SMTP configuration. The organization's default sender (see Set the Default Organization SMTP Custom Email) is returned first.

For cursor-based pagination over large lists, use List Organization SMTP Custom Emails (paginated) instead.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: Your token must be able to read SMTP custom emails in the target organization.
IDs: See our Get resource IDs page for how to find the organizationId. The optional smtpConfigurationId comes from List SMTP Configurations.

Step 1: Run the query

query ListSmtpCustomEmails($organizationId: ID!, $smtpConfigurationId: ID, $filter: [String]) {
  smtpCustomEmails(
    organizationId: $organizationId
    smtpConfigurationId: $smtpConfigurationId
    filter: $filter
  ) {
    id
    emailAddress
    senderName
    smtpConfiguration {
      id
      host
    }
  }
}

Variables

{
  "organizationId": "12345"
}

Step 2: Check the response

{
  "data": {
    "smtpCustomEmails": [
      {
        "id": 678,
        "emailAddress": "[email protected]",
        "senderName": "Your Company",
        "smtpConfiguration": {
          "id": 91,
          "host": "smtp.yourcompany.com"
        }
      },
      {
        "id": 679,
        "emailAddress": "[email protected]",
        "senderName": "Your Company Support",
        "smtpConfiguration": {
          "id": 91,
          "host": "smtp.yourcompany.com"
        }
      }
    ]
  }
}

Returned fields

Field	Description
`id`	The SMTP Custom Email ID — use it in Update, Delete, and Set the Default Organization SMTP Custom Email
`emailAddress`	The sender email address used for outbound messages
`senderName`	The display name shown to recipients
`smtpConfiguration.id`	The SMTP configuration this sender belongs to
`smtpConfiguration.host`	The SMTP server host of that configuration

Implementation notes

The result is limited to 30 custom emails, ordered by sender name; the organization's default sender (when set) is always first.
smtpConfigurationId narrows the list to the senders of one SMTP configuration.
filter accepts one or more strings matched against the email address (partial matches are supported).
Senders the token cannot read are filtered out of the result.