Skip to main content

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.

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.
A typed TypeScript SDK for integrations is coming with the next archie-app release. This page documents the GraphQL operation surface available today.

​
Enable the integration

Open Integrations in the left sidebar and pick SendGrid. You’ll need from your SendGrid dashboard:
  • 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

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: 
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: 
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-): 
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: 
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: 
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.

​
FAQ

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.
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.
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.
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.