Create 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

When you already have an SMTP configuration for an organization, you can attach a custom sender to it — defining the display name and email address used for outbound messages. If you need to create the sender and its SMTP configuration in one step, use Create SMTP Custom Email with Configuration instead.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must be able to manage SMTP custom emails in the target organization.
3. An SMTP configuration: Either pass an existing smtpConfigurationId, or pass organizationId to attach the sender to the organization's default SMTP configuration.

Step 1: Run the mutation

mutation CreateSmtpCustomEmail(
  $emailAddress: String!
  $senderName: String!
  $organizationId: ID
  $smtpConfigurationId: ID
) {
  createSmtpCustomEmail(
    input: {
      emailAddress: $emailAddress
      senderName: $senderName
      organizationId: $organizationId
      smtpConfigurationId: $smtpConfigurationId
    }
  ) {
    smtpCustomEmail {
      id
      emailAddress
      senderName
      smtpConfigurationId
    }
  }
}

Arguments

• emailAddress: String — Required — The email address for the sender.
• senderName: String — Required — Friendly display name for the sender.
• organizationId: ID — Optional — Attaches the sender to the organization's default SMTP configuration. Required if smtpConfigurationId is not provided.
• smtpConfigurationId: ID — Optional — Attaches the sender to a specific SMTP configuration. Required if organizationId is not provided.

You must provide either organizationId or smtpConfigurationId. Providing neither returns an input error.

Example variables

{
  "emailAddress": "[email protected]",
  "senderName": "Acme Support",
  "organizationId": "980700673"
}

Expected response

{
  "data": {
    "createSmtpCustomEmail": {
      "smtpCustomEmail": {
        "id": "a4f1b2c3-d4e5-6f78-9abc-d0e1f2a3b4c5",
        "emailAddress": "[email protected]",
        "senderName": "Acme Support",
        "smtpConfigurationId": "7e9f4d01-b412-43e0-999c-73e4f36889a9"
      }
    }
  }
}

Key notes

• When you pass organizationId, the sender is attached to the organization's default SMTP configuration. If the organization has no default configuration, the mutation returns an input error.
• The email address must be unique within the organization.
• To create the sender and a brand-new SMTP configuration together, use Create SMTP Custom Email with Configuration.