---

name: sendgrid-mail-management description: Implements features for sending emails, managing templates, handling marketing campaigns, and parsing inbound emails with the SendGrid API. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: agent triggers: sendgrid, send email, email templates, marketing campaigns, inbound email parsing role: implementation scope: implementation output-format: code related-skills: coding-sendgrid-api, coding-email-management archetypes:

• tactical
• operational
• generational anti_triggers:
• brainstorming
• vague ideation
• general discussions response_profile: verbosity: low directive_strength: high abstraction_level: operational

---

SendGrid Mail Management

This skill integrates the SendGrid API to manage email functionalities, including sending transactional emails, handling email templates, managing marketing campaigns, and parsing inbound emails. Upon loading, this skill allows the model to create well-structured emails, utilize dynamic templates, and process email responses via webhooks.

TL;DR Checklist

• Initialize SendGridAPIClient with SENDGRID_API_KEY from environment variables.
• Construct emails using the Mail helper, adjusting for dynamic templates.
• Configure tracking settings for analytics.
• Implement inbound email parsing to process responses.
• Catch API errors to handle failed requests properly.

---

When to Use

• When needing to send transactional emails through SendGrid.
• To manage and update email templates dynamically.
• For handling bulk marketing email campaigns.
• To parse and respond to inbound emails programmatically.

---

Core Workflow

1. Initialize the Client: Create a SendGridAPIClient using SENDGRID_API_KEY. Ensure proper authentication by checking available scopes before sending emails.
   • Checkpoint: Verify API scope for sending emails.
2. Construct the Mail Object: Use the Mail helper from sendgrid.helpers.mail to build the email. Specify from_email, to_emails, subject, and content as either HTML or plain text.
   • Checkpoint: Validate the mail object's structure before sending.
3. Handle Marketing Campaigns: Employ the marketing campaign API to create, send, and track the performance of email campaigns.
   • Checkpoint: Utilize categories and tags for group tracking.
4. Process Inbound Emails: Configure the inbound parse settings in SendGrid to redirect incoming emails to your application.
   • Checkpoint: Ensure webhook URL is correctly set in SendGrid for receiving events.
5. Send the Email: Call sg.send() with the constructed mail object, and handle responses appropriately.
   • Checkpoint: Parse and log the response for delivery verification.

---

Implementation Patterns

Pattern 1: Sending a Transactional Email

import os
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

def send_transactional_email(to_email, subject, html_content):
    sg = SendGridAPIClient(os.environ['SENDGRID_API_KEY'])
    message = Mail(
        from_email='noreply@example.com',
        to_emails=to_email,
        subject=subject,
        html_content=html_content,
    )
    try:
        response = sg.send(message)
        if response.status_code == 202:
            print(f"Email sent to {to_email} with status code {response.status_code}")
        else:
            print(f"Failed to send email. Status code: {response.status_code}")
    except Exception as e:
        print(f"An error occurred: {str(e)}")

Pattern 2: Dynamic Templates

def send_dynamic_template_email(to_email, template_id, dynamic_data):
    sg = SendGridAPIClient(os.environ['SENDGRID_API_KEY'])
    message = Mail(
        from_email='noreply@example.com',
        to_emails=to_email,
    )
    message.template_id = template_id
    message.dynamic_template_data = dynamic_data
    try:
        response = sg.send(message)
        print(f"Dynamic email sent, response code: {response.status_code}")
    except Exception as e:
        print(f"Failed to send dynamic email: {str(e)}")

Pattern 3: Inbound Email Processing

from flask import Flask, request
app = Flask(__name__)

@app.route('/inbound', methods=['POST'])
def inbound_webhook():
    email_data = request.json
    # Process email data here
    print(f"Received email from: {email_data['from']}")
    return "OK", 200

---

Constraints

MUST DO

• Store SENDGRID_API_KEY securely as an environment variable.
• Use the Mail helper instead of constructing HTTP request bodies manually.
• Validate all email addresses for deliverability before sending.
• Ensure proper logging of delivery status and errors for every email sent.

MUST NOT DO

• Attempt to send emails without verifying the sender account.
• Send bulk emails without implementing proper event tracking and unsubscribe links.

---

Related Skills

Skill	Purpose
coding-sendgrid-api	For general SendGrid API interactions
coding-email-management	For managing and sending emails through another platform

Live References

Authorative documentation links for this domain. The model follows markdown links at load time to resolve external references and inline content.

• SendGrid Mail Send API — Official SendGrid API reference for the /v3/mail/send endpoint
• SendGrid Dynamic Templates — Documentation on using dynamic templates with personalization variables
• SendGrid Web API Python SDK — Official SendGrid Python library source code and usage examples
• Email API Standards Comparison (Postmark, Mailgun, AWS SES) — Comparative reference for email sending platforms and their API approaches
• RFC 5322: Internet Message Format — IETF standard defining the format of email messages