DocumentationCustom SMTP (bring your own)

Custom SMTP (bring your own)

Send through your own SMTP server (for example Gmail) per project.

Each project can send through your own SMTP server instead of the shared transport — useful for a client's Gmail/Workspace mailbox or an existing relay. When a project has SMTP configured, its sends go out through it: it takes priority and does not fall back to the shared transport.

Configure

Set the SMTP fields on a project via the API (scope projects:write) or the dashboard:

PATCH /projects/{projectId}
Authorization: Bearer <apiKey or accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json

{
  "fromEmail": "[email protected]",
  "fromName": "Your Brand",
  "smtpHost": "smtp.gmail.com",
  "smtpPort": 465,
  "smtpSecure": true,
  "replyTo": "[email protected]"
}

Send your smtpUser and smtpPassword in the same body — both are documented in the table below.

Field	Notes
`smtpHost` / `smtpPort`	Your server. Port `465` + `smtpSecure: true`, or `587` + `smtpSecure: false`
`smtpUser` / `smtpPassword`	Credentials. The password is encrypted at rest (AES-256-GCM) and never returned
`smtpSecure`	TLS on connect. Defaults to `true`
`fromEmail` / `fromName` / `replyTo`	Sender identity for this project

The password is write-only: reads return smtpConfigured: true/false instead of the value. Send "smtpPassword": "" to clear it and fall back to the shared transport.

Verify the credentials

POST /projects/{projectId}/verify-smtp

This performs a live login handshake against your SMTP server and returns an error if it fails — the quickest way to confirm a Gmail app password works.

Gmail

Use a Gmail App Password (not your account password), and set host and port explicitly:

smtp.gmail.com, port 465, smtpSecure: true, or
smtp.gmail.com, port 587, smtpSecure: false.

How sending picks the transport

When you send with a projectId that has SMTP configured, the message goes through that SMTP server (provider: smtp). Otherwise MailingCore uses its shared, authenticated transport. See Send an email.