> 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/sendgrid.md).

# Twilio SendGrid

Connect Twilio SendGrid to Email.

Twilio SendGrid is a hosted email API: you need one API key and a verified sender.

## Get your credentials

1. Open the [SendGrid console](https://app.sendgrid.com/) and sign in.
2. **Settings → Sender Authentication:** authenticate your domain `acme.com` (recommended) or verify one sender `no-reply@acme.com`.
3. **Settings → API Keys → Create API Key:** choose **Restricted Access** with **Mail Send** = Full Access. Copy the key (`SG.…`) — SendGrid shows it once.

## Connect it in Cloud

**Where:** Email → Integrations → **Add New Integration** → Twilio SendGrid → **Connect** · `/projects/<project>/emails/integrations/new/twilio-sendgrid`

| Field                   | Required | What it does                                                                           | Example              |
| ----------------------- | -------- | -------------------------------------------------------------------------------------- | -------------------- |
| Sender Email Address    | yes      | A verified sender, or an address on the authenticated domain.                          | `hello@acme.example` |
| Sender Display Name     | no       | The "from" name.                                                                       | `Acme`               |
| Twilio SendGrid API Key | yes      | The `SG.…` key. Stored encrypted and never shown again; to change it, paste a new key. | `SG.…`               |
| Integration Name        | yes      | The name in Norbix.                                                                    | `SendGrid (example)` |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-7ab449b46ea62446eab5ca4f08f0e02041a15ea6%2Fsendgrid-1.png?alt=media" alt="New Twilio SendGrid Integration form filled with made-up values: Sender Email Address, Sender Display Name, API key, Integration Name"><figcaption><p>The filled form (made-up values).</p></figcaption></figure>

Press **Save**. The integration opens with its id and the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**; the API key field stays empty with an **Info** note that the key is not shown again.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0a47d891d4afe123cf073c51d5057eb235324610%2Fsendgrid-2.png?alt=media" alt="Editing Twilio SendGrid integration: badges ENABLED, NOT TESTED, NOT CONFIRMED, Sender Email Address hello@acme.example, Twilio SendGrid API Key empty with an Info note"><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)). Bounces and opens do not come back into Norbix from SendGrid; check them in SendGrid's activity feed.

## Common errors

| Message                                  | Cause                                                     | Fix                                           |
| ---------------------------------------- | --------------------------------------------------------- | --------------------------------------------- |
| Test failed, SendGrid refuses the sender | The **Sender Email Address** is not verified in SendGrid. | Verify the sender or authenticate the domain. |
| Test failed, unauthorized                | The key is wrong or has no **Mail Send** access.          | Create a new key with Mail Send and save it.  |
| Big campaigns stop part way              | The SendGrid plan's daily limit was reached.              | Raise the plan or split the campaign.         |

## Do it from code

```ts
const { id } = await norbix.hub.notifications.saveEmailIntegration({
  integration: {
    provider: 'SendGrid',
    integrationName: 'SendGrid (example)',
    isEnabled: true,
    emailAddress: 'hello@acme.example',
    emailSenderName: 'Acme',
    apiKey: process.env.SENDGRID_API_KEY ?? 'SG.made-up-key',
  },
});
```

```sh
norbix hub notifications email integration save --integration '{"provider":"SendGrid","integrationName":"SendGrid (example)","isEnabled":true,"emailAddress":"hello@acme.example","emailSenderName":"Acme","apiKey":"SG.made-up-key"}'
```

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