> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpacarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SendGrid

> Connect SendGrid with an API key to import dynamic templates and push AlpacaRelay designs back as dynamic transactional templates.

Connecting SendGrid lets you import your dynamic transactional templates and push AlpacaRelay designs back out as dynamic templates your application can send with.

<Info>
  New to integrations? The [overview](/integrations/overview) explains the import and export flows that are the same for every provider. This page covers what's specific to SendGrid.
</Info>

## What you need

* A Twilio SendGrid account.
* A SendGrid API key with access to templates and account information.

SendGrid doesn't offer OAuth for this, so you create an API key and paste it in once.

## Create the API key

<Steps>
  <Step title="Open API keys in SendGrid">
    In SendGrid, go to **Settings** → **API Keys** and click **Create API Key**.
  </Step>

  <Step title="Name it something recognizable">
    `AlpacaRelay` works — the name is only for your own audit trail later.
  </Step>

  <Step title="Choose Restricted Access">
    Then grant only these permissions:

    | Permission      | Access      | Why                                                           |
    | --------------- | ----------- | ------------------------------------------------------------- |
    | Template Engine | Full Access | Read, create, and update your dynamic templates               |
    | User Account    | Read Access | Confirms the connection and shows which account you connected |

    Leave everything else off. **Mail Send** is not needed — AlpacaRelay never sends through your SendGrid account.
  </Step>

  <Step title="Copy the key">
    SendGrid shows the key exactly once. Copy it before leaving the page.
  </Step>
</Steps>

<Warning>
  A Full Access key works too, but it can send mail and change billing on your account. Prefer the restricted key above.
</Warning>

## Connect SendGrid

<Steps>
  <Step title="Open Connected apps">
    Go to **Settings** → **Connected apps**, then click **Connect app**.
  </Step>

  <Step title="Choose SendGrid">
    A secure form opens, asking for your API key.
  </Step>

  <Step title="Paste the key">
    Paste the key you just created and submit. AlpacaRelay verifies it immediately by reading your account information.
  </Step>

  <Step title="Check the badge">
    SendGrid appears in your connected apps with a **Connected** badge and your SendGrid username or account email.
  </Step>
</Steps>

<Note>
  Your API key is stored encrypted and is never shown back to you or exposed to the browser. To rotate it, create a new key in SendGrid, then **Reconnect** here and paste the new one.
</Note>

## Export a design to SendGrid

Save the email, then open **Send to app** from the editor's name dropdown or the **⋯** menu on an email card, and click **Create template** on the SendGrid row.

The export creates a **dynamic transactional template** and an **active version** inside it holding your design. You'll find it under **Email API** → **Dynamic Templates** in SendGrid.

Because the version is marked active, your application can send it by template ID straight away — no extra step in SendGrid.

**Re-sync** updates the active version of that same template. The template ID stays the same, so code already sending that ID picks up the new design on its next send.

<Tip>
  Grab the template ID from SendGrid once and your application never needs to change it again, however many times you re-sync the design.
</Tip>

Plain text is regenerated from the design on each sync, so the text alternative stays in step with the HTML.

## Import a template from SendGrid

Click **Import** when creating an email, choose **SendGrid** under **Integrations**, and pick a template.

The picker lists your **dynamic** templates and reads the HTML from each one's active version. SendGrid provides thumbnails for most templates, so rows show a preview.

<Warning>
  SendGrid's older **legacy** transactional templates aren't listed. Only dynamic templates appear. If a template you expect is missing, it's likely a legacy one — recreate it as dynamic in SendGrid, or export its HTML and use **Paste code** instead.
</Warning>

A dynamic template with no active version has no HTML to read, so it appears greyed out.

Handlebars syntax such as `{{first_name}}` imports as literal text. AlpacaRelay doesn't interpret it, so it survives the round trip and still resolves when SendGrid sends.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connecting failed immediately">
    The key is missing **User Account** read access, was truncated when copied, or has already been deleted in SendGrid. Create a fresh restricted key and try again.
  </Accordion>

  <Accordion title="The connection flipped to Needs attention">
    The API key was deleted or rotated in SendGrid. Create a new one, click **Reconnect**, and paste it.
  </Accordion>

  <Accordion title="Export fails but the connection looks fine">
    The key can probably read your account but not write templates. Check that **Template Engine** is set to Full Access, not Read Access.
  </Accordion>

  <Accordion title="My template isn't in the import picker">
    Only dynamic templates with an active version are listed. Legacy templates never appear.
  </Accordion>
</AccordionGroup>