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

# SendGrid

> Send transactional and marketing email — single sends, bulk sends, dynamic templates, contact management, and delivery analytics.

The SendGrid integration sends email from your Archie app. Once connected, Archie exposes namespaced GraphQL operations (`sendgrid_*`) for sending, managing contacts, and reading delivery stats.

<Note>
  A typed TypeScript SDK for integrations is coming with the next archie-app release. This page documents the GraphQL operation surface available today.
</Note>

## Enable the integration

Open **Integrations** in the left sidebar and pick SendGrid.

You'll need from your [SendGrid dashboard](https://app.sendgrid.com/settings/api_keys):

* **API Key** — generated in **Settings → API Keys**. Give it Mail Send permissions at minimum; add Marketing for contact and template features.
* **Environment** — pick the environment context (`Production`, `Staging`, or a custom tag) so credentials route correctly.

The API key is encrypted at rest and only decrypted at request time inside the backend.

## What you can do

The integration adds operations across SendGrid's core surfaces:

* **Send** — `sendgrid_sendEmail`, `sendgrid_sendBulkEmail`, `sendgrid_sendTemplate`
* **Contacts** — `sendgrid_addContact`, `sendgrid_updateContact`, `sendgrid_deleteContact`
* **Analytics** — `sendgrid_getEmailStats`, `sendgrid_validateEmail`

## Sending email

### A simple transactional email

```graphql theme={null}
mutation {
  sendgrid_sendEmail(email: {
    from: { email: "hello@yourapp.com", name: "Yourapp" }
    to: { email: "ada@example.com", name: "Ada" }
    subject: "Welcome to Yourapp"
    content: { type: "text/html", value: "<h1>Welcome</h1><p>Glad you're here.</p>" }
  }) {
    messageId
    success
  }
}
```

### CC, BCC, and attachments

`to`, `cc`, and `bcc` accept arrays of recipients. Attachments are passed as base64-encoded content:

```graphql theme={null}
mutation {
  sendgrid_sendEmail(email: {
    from: { email: "hello@yourapp.com" }
    to:  [{ email: "ada@example.com" }]
    cc:  [{ email: "team@yourapp.com" }]
    subject: "Receipt"
    content: [{ type: "text/html", value: "<p>Receipt attached.</p>" }]
    attachments: [{
      filename: "receipt.pdf"
      type: "application/pdf"
      content: "JVBERi0..."
      disposition: "attachment"
    }]
  }) {
    messageId
    success
  }
}
```

### Scheduled email

Pass `sendAt` with an ISO 8601 timestamp to defer delivery:

```graphql theme={null}
mutation {
  sendgrid_sendEmail(email: {
    from: { email: "hello@yourapp.com" }
    to:  [{ email: "ada@example.com" }]
    subject: "Reminder: invoice due"
    content: [{ type: "text/html", value: "<p>Heads up.</p>" }]
    sendAt: "2026-06-01T10:00:00Z"
  }) {
    messageId
    success
  }
}
```

### Dynamic templates

For richer designs, use a SendGrid Dynamic Template (the template ID starts with `d-`):

```graphql theme={null}
mutation {
  sendgrid_sendTemplate(email: {
    from: { email: "hello@yourapp.com" }
    to:  [{ email: "ada@example.com" }]
    templateId: "d-1234567890abcdef"
    substitutions: {
      name: "Ada"
      orderNumber: "12345"
      totalAmount: "$99.99"
    }
  }) {
    messageId
    success
  }
}
```

### Bulk sends

`sendgrid_sendBulkEmail` accepts an array of email payloads in a single call. Useful for onboarding sequences and one-off campaigns under SendGrid's limits.

## Contacts

Add, update, and delete recipients in your SendGrid contact lists:

```graphql theme={null}
mutation {
  sendgrid_addContact(contact: {
    email: "ada@example.com"
    firstName: "Ada"
    lastName: "Lovelace"
    customFields: { plan: "founder" }
    listIds: ["a1b2c3..."]
  })
}
```

## Analytics

Pull aggregate delivery metrics for a date range:

```graphql theme={null}
query {
  sendgrid_getEmailStats(startDate: "2026-04-01", endDate: "2026-04-30") {
    delivered
    opens
    clicks
    bounces
    spamReports
  }
}
```

`sendgrid_validateEmail` checks an address's deliverability score before you send.

## Webhooks

In SendGrid, go to **Settings → Mail Settings → Event Webhook** and point it at the Archie-generated webhook URL for your project. Configure the webhook signing key so Archie can verify events. Supported events include `processed`, `delivered`, `opened`, `clicked`, `bounce`, `dropped`, `spamreport`, and `unsubscribe`. See [Webhooks](/features/backend/integrations/webhooks).

## FAQ

<AccordionGroup>
  <Accordion title="What sender domains can I use?">
    Any domain you've authenticated in SendGrid. Domain authentication (SPF, DKIM) is required for reliable deliverability — single-sender verification works for testing but limits volume.
  </Accordion>

  <Accordion title="Why is my email going to spam?">
    Almost always a sender authentication issue. Make sure you've completed domain authentication in SendGrid, set up DMARC, and that your `from` address matches the authenticated domain. Warm new domains by sending gradually-increasing volume.
  </Accordion>

  <Accordion title="Can I send marketing emails through this integration?">
    Yes, including dynamic templates and contact list segmentation. For high-volume marketing campaigns specifically, SendGrid's Marketing Campaigns UI gives you scheduling and analytics that the API doesn't expose.
  </Accordion>

  <Accordion title="My API key returned 403 on email validation. What happened?">
    SendGrid's email validation endpoint requires a paid Email Validation add-on. If your key doesn't have it, `sendgrid_validateEmail` falls back to a basic regex check and returns a slightly lower score with a note explaining why.
  </Accordion>

  <Accordion title="How do I track which user clicked a link?">
    Pass a `customArgs` object on the send. SendGrid attaches it to every event for that message — Archie surfaces those custom args in the webhook events you receive.
  </Accordion>
</AccordionGroup>