Create SMTP connection
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
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
typeisoauth2type(oauth2, required): Set tooauth2to send report emails through a Google or Microsoft account you connected to Rollstack, chosen withservice, 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.gmailis Gmail, from the Google account with the same email as your Rollstack account.gmail_oauthis Gmail, from another Google account you connected for sending.outlookis 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, whichlistSmtpConnectionsreturns. One ofgmail,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 accountservicepoints to, and withgmail_oauthand several Google accounts connected for sending, that may not be this one. If you already have a connection with the sameserviceandusername, Rollstack returns it instead of creating another, keeping itsfrom; withorganizationSmtpConfigtrue, it also shares it. Example:reports@acme.com.from(string, required): The sender address report emails sent through this connection go out from, asemail@domain.comorName <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 passingtruegets a403. If omitted orfalse, only you can choose it as a sender.
- When
typeislogintype(login, required): Set tologinto send report emails through an SMTP server that Rollstack signs in to withusernameandpassword, such as your company's mail server or an email provider's SMTP service.service(string, required): Alwaysmanual: the SMTP server is set up by hand withhost,port,usernameandpassword, like the Manual option in the app. One ofmanual.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 port465), so the server must accept TLS on that port from the start, not only after STARTTLS. One of25,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, asemail@domain.comorName <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 passingtruegets a403. If omitted orfalse, only you can choose it as a sender.
Response 201
Success
application/json
id(string, required): Unique identifier for the SMTP connection. Pass it assmtpServerIdtoupdateReportEmailConfigto send a report's emails through it, or asidtodeleteSmtpConnection.from(string, required): The sender address report emails sent through this connection go out from, asemail@domain.comorName <email@domain.com>.type(string, required): How the connection sends report emails.loginsigns in to an SMTP server with a username and password (seehost,portandusername).oauth2sends through a Google or Microsoft account its owner connected to Rollstack (seeservice), with no password stored, and only while that account stays connected with permission to send email. One oflogin,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 withhost,port,usernameand a password (typelogin).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.
nullwhen 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 aloginconnection signs in to, such assmtp.acme.com.nullfor anoauth2connection, 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 aloginconnection.nullfor anoauth2connection.username(string or null, required): For aloginconnection, the username Rollstack signs in to the SMTP server with. For anoauth2connection, the email address recorded when it was created; emails go out through the accountservicepoints to, which forgmail_oauthmay be another of the owner's connected Google accounts. Nevernullon connections created in the app or the API.organizationShared(boolean, required): Whether the connection is shared with the organization. Whentrue, every member can choose it as the sender of their reports' emails, which then go out through the owner's account or server login. Whenfalse, 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 theiridinlistMembers; your own connections carry youridfromgetMe. Only the owner can delete the connection, and anoauth2connection sends through the owner's account.createdAt(string (date-time), required): When the connection was added.listSmtpConnectionslists the newest first.