Skip to main content

Create SMTP connection

POST https://api.rollstack.com/public/v1/smtp-connections

Adds an SMTP connection after sending a test email through it. Only owners and admins may share it with the organization.

Requires the smtp:write scope.

Operation ID: createSmtpConnection.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • When type is oauth2
    • type (oauth2, required): Set to oauth2 to send report emails through a Google or Microsoft account you connected to Rollstack, chosen with service, rather than through an SMTP server. Rollstack stores no password for it, and the connection sends only while that account stays connected with permission to send email.
    • service (string, required): Which of your accounts sends the emails. gmail is Gmail, from the Google account with the same email as your Rollstack account. gmail_oauth is Gmail, from another Google account you connected for sending. outlook is Outlook, from your Microsoft account. The account must already be connected with permission to send email, under Settings > Connected apps > Sending email in the app, or creating the connection fails. Connecting an account there already creates an SMTP connection for it, which listSmtpConnections returns. One of gmail, outlook, gmail_oauth.
    • username (string, required): The email address of the Google or Microsoft account the connection is for, recorded to tell your connections apart. It doesn't choose the account that sends: emails go out through the account service points to, and with gmail_oauth and several Google accounts connected for sending, that may not be this one. If you already have a connection with the same service and username, Rollstack returns it instead of creating another, keeping its from; with organizationSmtpConfig true, it also shares it. Example: reports@acme.com.
    • from (string, required): The sender address report emails sent through this connection go out from, as email@domain.com or Name <email@domain.com>. Rollstack sends a test email from it before saving the connection; if that email fails, the connection isn't created. Example: Acme Reports <reports@acme.com>.
    • organizationSmtpConfig (boolean): Whether to share the connection with your organization, so every member can choose it as the sender of their reports' emails; their emails then go out through your account or server login. Only owners and admins can share a connection: anyone else passing true gets a 403. If omitted or false, only you can choose it as a sender.
  • When type is login
    • type (login, required): Set to login to send report emails through an SMTP server that Rollstack signs in to with username and password, such as your company's mail server or an email provider's SMTP service.
    • service (string, required): Always manual: the SMTP server is set up by hand with host, port, username and password, like the Manual option in the app. One of manual.
    • host (string, required): The address of the SMTP server to send through, as your email provider or IT team gives it. Example: smtp.acme.com.
    • port (number, required): The port Rollstack connects to on the SMTP server. Rollstack starts TLS as soon as it connects (implicit TLS, usually on port 465), so the server must accept TLS on that port from the start, not only after STARTTLS. One of 25, 465, 587, 2525.
    • username (string, required): The username Rollstack signs in to the SMTP server with, often the mailbox's email address. Example: reports@acme.com.
    • password (string, required): The password Rollstack signs in to the SMTP server with. For a Gmail or Outlook mailbox, this is usually an app password. The API never returns it. Example: your-smtp-password.
    • from (string, required): The sender address report emails sent through this connection go out from, as email@domain.com or Name <email@domain.com>. Rollstack sends a test email from it before saving the connection; if that email fails, the connection isn't created. Example: Acme Reports <reports@acme.com>.
    • organizationSmtpConfig (boolean): Whether to share the connection with your organization, so every member can choose it as the sender of their reports' emails; their emails then go out through your account or server login. Only owners and admins can share a connection: anyone else passing true gets a 403. If omitted or false, only you can choose it as a sender.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the SMTP connection. Pass it as smtpServerId to updateReportEmailConfig to send a report's emails through it, or as id to deleteSmtpConnection.
  • from (string, required): The sender address report emails sent through this connection go out from, as email@domain.com or Name <email@domain.com>.
  • type (string, required): How the connection sends report emails. login signs in to an SMTP server with a username and password (see host, port and username). oauth2 sends through a Google or Microsoft account its owner connected to Rollstack (see service), with no password stored, and only while that account stays connected with permission to send email. One of login, oauth2.
  • service (string or null, required): Which account or server the connection sends through:

    • gmail: Gmail, from the owner's Google account with the same email as their Rollstack account.
    • gmail_oauth: Gmail, from another Google account the owner connected for sending.
    • outlook: Outlook, from the owner's Microsoft account.
    • manual: an SMTP server set up by hand with host, port, username and a password (type login).
    • resend: Rollstack's own sending service, which report emails use when no connection is chosen. No connection created in the app or the API has it.

    null when no service is recorded; the app shows such a connection as Manual.

    One of gmail_oauth, gmail, outlook, resend, manual.

  • host (string or null, required): The address of the SMTP server a login connection signs in to, such as smtp.acme.com. null for an oauth2 connection, which sends through a Google or Microsoft account rather than an SMTP server.
  • port (number or null, required): The port Rollstack connects to on the SMTP server of a login connection. null for an oauth2 connection.
  • username (string or null, required): For a login connection, the username Rollstack signs in to the SMTP server with. For an oauth2 connection, the email address recorded when it was created; emails go out through the account service points to, which for gmail_oauth may be another of the owner's connected Google accounts. Never null on connections created in the app or the API.
  • organizationShared (boolean, required): Whether the connection is shared with the organization. When true, every member can choose it as the sender of their reports' emails, which then go out through the owner's account or server login. When false, only the owner can choose it. A shared connection can't be deleted until an owner or admin unshares it in the app.
  • ownerUserId (number, required): The member who added the connection and owns it, as their id in listMembers; your own connections carry your id from getMe. Only the owner can delete the connection, and an oauth2 connection sends through the owner's account.
  • createdAt (string (date-time), required): When the connection was added. listSmtpConnections lists the newest first.