Skip to main content

List SMTP connections

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

The user's SMTP connections and the ones shared with the organization, without their credentials.

Requires the smtp:read scope.

Operation ID: listSmtpConnections.

Response 200

Success

application/json: array of object

  • 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.