> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/emails/integrations/providers/smtp.md).

# SMTP

Connect any SMTP mail server to Email.

SMTP is the standard way to hand an email to a mail server, so this integration works with almost any provider — including your company mail server or a local mail catcher on a self-hosted install.

## Get your credentials

1. Open your mail provider's admin console (for example the "SMTP" or "App passwords" page) and sign in.
2. Create SMTP credentials for the sending account — often an app password — and note the host and the port (`587` with TLS in most cases).

## Connect it in Cloud

**Where:** Email → Integrations → **Add New Integration** → SMTP → **Connect** · `/projects/<project>/emails/integrations/new/smtp`

| Field                | Required | What it does                                                            | Example                 |
| -------------------- | -------- | ----------------------------------------------------------------------- | ----------------------- |
| Sender Email Address | yes      | The "from" address; many servers accept only the signed-in account.     | `no-reply@acme.example` |
| Sender Display Name  | no       | The "from" name.                                                        | `Acme`                  |
| SMTP Host Name       | yes      | A host name or IP address of the server.                                | `smtp.acme.example`     |
| User Name            | yes      | The SMTP user.                                                          | `acme-mailer`           |
| Password             | yes      | The SMTP password or app password. Stored encrypted, never shown again. | —                       |
| Port                 | no       | `25`, `465`, `587` or `2525`.                                           | `587`                   |
| Integration Name     | yes      | The name in Norbix.                                                     | `Acme SMTP`             |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-5b9b4251c749f71402fafcaa80924f1ed609c3ec%2Fsmtp-1.png?alt=media" alt="New SMTP Integration form filled with made-up values: Sender Email Address hello@acme.example, Sender Display Name Acme, SMTP Host Name smtp.acme.example, User Name acme-mailer"><figcaption><p>The filled form (made-up values).</p></figcaption></figure>

Press **Save**. The integration opens with its id and badges. Below: a test sent to a local mail catcher (Mailpit) on port `2525`.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ba4e96edb727ac76c90fbaf11303c4987372bac3%2Fsmtp-2.png?alt=media" alt="Editing SMTP integration Mailpit (local test): badges ENABLED, TESTED, NOT CONFIRMED; Sender Email Address no-reply@acme.example; SMTP Host Name smtp.dsem.norbix.test"><figcaption><p>After save.</p></figcaption></figure>

## Test and set as default

On the saved integration: **Test Email Recipient** → **Test integration** → **I received it** ([Test an integration](/codemash/cloud/emails/integrations/test.md)), then **Actions → Set as default** ([Set as default](/codemash/cloud/emails/integrations/set-default.md)). No delivery events (bounces, opens) come back from an SMTP server.

## Common errors

| Message                                                                               | Cause                                                                                                 | Fix                                                           |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `Could not send email via Smtp. Received status: 503. Message: Failure sending mail.` | Norbix could not reach the server on that host and port (here: a port the server does not listen on). | Check **SMTP Host Name** and **Port**, save, test again.      |
| A host name is refused on **Save**                                                    | The host is not a valid host name.                                                                    | Use a full host name or an IP address.                        |
| The server refuses the sender                                                         | The **Sender Email Address** is not the signed-in account.                                            | Use the account's address, or allow the sender on the server. |
| Nothing arrives on port 25                                                            | Cloud hosts often block port 25.                                                                      | Use `587` or `2525`.                                          |

SMTP is slower than an API for large campaigns; consider SES, SendGrid or Mailgun for big lists.

## Do it from code

```ts
const { id } = await norbix.hub.notifications.saveEmailIntegration({
  integration: {
    provider: 'Smtp',
    integrationName: 'Office mail server',
    isEnabled: true,
    emailAddress: 'no-reply@acme.example',
    emailSenderName: 'Acme',
    domain: 'smtp.dsem.norbix.test', // your SMTP host
    port: 2525,
    userName: 'acme-mailer',
    password: process.env.SMTP_PASSWORD ?? 'local-catcher',
  },
});
```

```sh
norbix hub notifications email integration test --integrationId int_7bl0e6pSQmGzNFLp2P6rcd --to ada.lovelace@example.com
```

API: [Save Email Integration](/codemash/api-reference/notifications/email/save-email-integration.md) · [Test Email Integration](/codemash/api-reference/notifications/email/test-email-integration.md)