SendGrid

Access the SendGrid API with managed OAuth authentication. Send transactional and marketing emails, manage contacts, templates, suppressions, and analyze email performance.

All SendGrid API endpoints follow this pattern:

/sendgrid/v3/{resource}

Reference

Send Email

POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com", "name": "Recipient"}],
      "subject": "Hello from SendGrid"
    }
  ],
  "from": {"email": "sender@example.com", "name": "Sender"},
  "content": [
    {
      "type": "text/plain",
      "value": "This is a test email."
    }
  ]
}

With HTML content:

POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com"}],
      "subject": "HTML Email"
    }
  ],
  "from": {"email": "sender@example.com"},
  "content": [
    {
      "type": "text/html",
      "value": "<h1>Hello</h1><p>This is an HTML email.</p>"
    }
  ]
}

With template:

POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "recipient@example.com"}],
      "dynamic_template_data": {
        "first_name": "John",
        "order_id": "12345"
      }
    }
  ],
  "from": {"email": "sender@example.com"},
  "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Get User Profile

GET /sendgrid/v3/user/profile

Response:

{
  "type": "user",
  "userid": 59796657
}

Get Account Details

GET /sendgrid/v3/user/account

List Contacts

GET /sendgrid/v3/marketing/contacts

Response:

{
  "result": [],
  "contact_count": 0,
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/contacts"
  }
}

Search Contacts

POST /sendgrid/v3/marketing/contacts/search
Content-Type: application/json

{
  "query": "email LIKE '%@example.com%'"
}

Add/Update Contacts

PUT /sendgrid/v3/marketing/contacts
Content-Type: application/json

{
  "contacts": [
    {
      "email": "contact@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  ]
}

Response:

{
  "job_id": "2387e363-4104-4225-8960-4a5758492351"
}

Note: Contact operations are asynchronous. Use the job status endpoint to check progress.

Get Import Job Status

GET /sendgrid/v3/marketing/contacts/imports/{job_id}

Response:

{
  "id": "2387e363-4104-4225-8960-4a5758492351",
  "status": "pending",
  "job_type": "upsert_contacts",
  "results": {
    "requested_count": 1,
    "created_count": 1
  },
  "started_at": "2026-02-11T11:00:14Z"
}

Delete Contacts

DELETE /sendgrid/v3/marketing/contacts?ids=contact_id_1,contact_id_2

Get Contact by ID

GET /sendgrid/v3/marketing/contacts/{contact_id}

Get Contact by Email

POST /sendgrid/v3/marketing/contacts/search/emails
Content-Type: application/json

{
  "emails": ["contact@example.com"]
}

List All Lists

GET /sendgrid/v3/marketing/lists

Response:

{
  "result": [],
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token="
  }
}

Create List

POST /sendgrid/v3/marketing/lists
Content-Type: application/json

{
  "name": "My Contact List"
}

Response:

{
  "name": "My Contact List",
  "id": "b050f139-4231-47c8-bf32-94ad76376d3b",
  "contact_count": 0,
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/lists/b050f139-4231-47c8-bf32-94ad76376d3b"
  }
}

Get List by ID

GET /sendgrid/v3/marketing/lists/{list_id}

Update List

PATCH /sendgrid/v3/marketing/lists/{list_id}
Content-Type: application/json

{
  "name": "Updated List Name"
}

Delete List

DELETE /sendgrid/v3/marketing/lists/{list_id}

Add Contacts to List

PUT /sendgrid/v3/marketing/contacts
Content-Type: application/json

{
  "list_ids": ["list_id"],
  "contacts": [
    {"email": "contact@example.com"}
  ]
}

List Segments

GET /sendgrid/v3/marketing/segments

Create Segment

POST /sendgrid/v3/marketing/segments
Content-Type: application/json

{
  "name": "Active Users",
  "query_dsl": "email_clicks > 0"
}

Get Segment by ID

GET /sendgrid/v3/marketing/segments/{segment_id}

Delete Segment

DELETE /sendgrid/v3/marketing/segments/{segment_id}

List Templates

GET /sendgrid/v3/templates

With generation filter:

GET /sendgrid/v3/templates?generations=dynamic

Create Template

POST /sendgrid/v3/templates
Content-Type: application/json

{
  "name": "My Template",
  "generation": "dynamic"
}

Response:

{
  "id": "d-ffcdb43ed8a04beba48a702e1717ddb5",
  "name": "My Template",
  "generation": "dynamic",
  "updated_at": "2026-02-11 11:00:20",
  "versions": []
}

Get Template by ID

GET /sendgrid/v3/templates/{template_id}

Update Template

PATCH /sendgrid/v3/templates/{template_id}
Content-Type: application/json

{
  "name": "Updated Template Name"
}

Delete Template

DELETE /sendgrid/v3/templates/{template_id}

Create Template Version

POST /sendgrid/v3/templates/{template_id}/versions
Content-Type: application/json

{
  "name": "Version 1",
  "subject": "{{subject}}",
  "html_content": "<html><body><h1>Hello {{name}}</h1></body></html>",
  "active": 1
}

Response:

{
  "id": "54230a99-1e89-4edf-821d-d4925b40c64b",
  "template_id": "d-ffcdb43ed8a04beba48a702e1717ddb5",
  "active": 1,
  "name": "Version 1",
  "html_content": "<html><body><h1>Hello {{name}}</h1></body></html>",
  "plain_content": "Hello {{name}}",
  "generate_plain_content": true,
  "subject": "{{subject}}",
  "editor": "code",
  "thumbnail_url": "//..."
}

List Senders

GET /sendgrid/v3/senders

Create Sender

POST /sendgrid/v3/senders
Content-Type: application/json

{
  "nickname": "My Sender",
  "from": {"email": "sender@example.com", "name": "Sender Name"},
  "reply_to": {"email": "reply@example.com", "name": "Reply To"},
  "address": "123 Main St",
  "city": "San Francisco",
  "country": "USA"
}

Response:

{
  "id": 8513177,
  "nickname": "My Sender",
  "from": {"email": "sender@example.com", "name": "Sender Name"},
  "reply_to": {"email": "reply@example.com", "name": "Reply To"},
  "address": "123 Main St",
  "city": "San Francisco",
  "country": "USA",
  "verified": {"status": false, "reason": null},
  "updated_at": 1770786031,
  "created_at": 1770786031,
  "locked": false
}

Note: Sender verification is required before use. Check verified.status.

Get Sender by ID

GET /sendgrid/v3/senders/{sender_id}

Update Sender

PATCH /sendgrid/v3/senders/{sender_id}
Content-Type: application/json

{
  "nickname": "Updated Sender Name"
}

Delete Sender

DELETE /sendgrid/v3/senders/{sender_id}

Bounces

# List bounces
GET /sendgrid/v3/suppression/bounces

# Get bounce by email
GET /sendgrid/v3/suppression/bounces/{email}

# Delete bounces
DELETE /sendgrid/v3/suppression/bounces
Content-Type: application/json

{
  "emails": ["bounce@example.com"]
}

Blocks

# List blocks
GET /sendgrid/v3/suppression/blocks

# Get block by email
GET /sendgrid/v3/suppression/blocks/{email}

# Delete blocks
DELETE /sendgrid/v3/suppression/blocks
Content-Type: application/json

{
  "emails": ["blocked@example.com"]
}

Invalid Emails

# List invalid emails
GET /sendgrid/v3/suppression/invalid_emails

# Delete invalid emails
DELETE /sendgrid/v3/suppression/invalid_emails
Content-Type: application/json

{
  "emails": ["invalid@example.com"]
}

Spam Reports

# List spam reports
GET /sendgrid/v3/suppression/spam_reports

# Delete spam reports
DELETE /sendgrid/v3/suppression/spam_reports
Content-Type: application/json

{
  "emails": ["spam@example.com"]
}

Global Unsubscribes

# List global unsubscribes
GET /sendgrid/v3/suppression/unsubscribes

# Add to global unsubscribes
POST /sendgrid/v3/asm/suppressions/global
Content-Type: application/json

{
  "recipient_emails": ["unsubscribe@example.com"]
}

List Groups

GET /sendgrid/v3/asm/groups

Create Group

POST /sendgrid/v3/asm/groups
Content-Type: application/json

{
  "name": "Weekly Newsletter",
  "description": "Weekly newsletter updates"
}

Response:

{
  "name": "Weekly Newsletter",
  "id": 122741,
  "description": "Weekly newsletter updates",
  "is_default": false
}

Get Group by ID

GET /sendgrid/v3/asm/groups/{group_id}

Update Group

PATCH /sendgrid/v3/asm/groups/{group_id}
Content-Type: application/json

{
  "name": "Updated Group Name"
}

Delete Group

DELETE /sendgrid/v3/asm/groups/{group_id}

Add Suppressions to Group

POST /sendgrid/v3/asm/groups/{group_id}/suppressions
Content-Type: application/json

{
  "recipient_emails": ["user@example.com"]
}

List Suppressions in Group

GET /sendgrid/v3/asm/groups/{group_id}/suppressions

Get Global Stats

GET /sendgrid/v3/stats?start_date=2026-02-01

With end date:

GET /sendgrid/v3/stats?start_date=2026-02-01&end_date=2026-02-28

Response:

[
  {
    "date": "2026-02-01",
    "stats": [
      {
        "metrics": {
          "blocks": 0,
          "bounce_drops": 0,
          "bounces": 0,
          "clicks": 0,
          "deferred": 0,
          "delivered": 0,
          "invalid_emails": 0,
          "opens": 0,
          "processed": 0,
          "requests": 0,
          "spam_report_drops": 0,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 0,
          "unsubscribe_drops": 0,
          "unsubscribes": 0
        }
      }
    ]
  }
]

Category Stats

GET /sendgrid/v3/categories/stats?start_date=2026-02-01&categories=category1,category2

Mailbox Provider Stats

GET /sendgrid/v3/mailbox_providers/stats?start_date=2026-02-01

Browser Stats

GET /sendgrid/v3/browsers/stats?start_date=2026-02-01

Credential management. API key operations create, modify, or delete long-lived SendGrid credentials that persist independently of the Maton OAuth session. A created key can be used outside this integration. Only invoke when the user explicitly requests API key management. Never log or display created key values.

List API Keys

GET /sendgrid/v3/api_keys

Response:

{
  "result": [
    {
      "name": "MatonTest",
      "api_key_id": "WJBgv5EKR8y0nn2F8Qfk5w"
    }
  ]
}

Create API Key

POST /sendgrid/v3/api_keys
Content-Type: application/json

{
  "name": "New API Key",
  "scopes": ["mail.send", "alerts.read"]
}

Get API Key by ID

GET /sendgrid/v3/api_keys/{api_key_id}

Update API Key

PATCH /sendgrid/v3/api_keys/{api_key_id}
Content-Type: application/json

{
  "name": "Updated Key Name"
}

Delete API Key

DELETE /sendgrid/v3/api_keys/{api_key_id}

SendGrid

On this page