Operations (sample payloads)
Main operations
Add contacts to list - Legacy
Add up to 1,000 contacts in your SendGrid database to a list in SendGrid. (Legacy Marketing Campaigns) Sample Input
\{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"list_id": 12345,
"contact_ids": [
"a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
"b2c3d4e5-f6g7-8h9i-0j1k-l2m3n4o5p6q7",
"c3d4e5f6-g7h8-9i0j-1k2l-m3n4o5p6q7r8"
]
\}
Sample Output
Create custom field – New
Create a new custom field in your SendGrid account. (New Marketing Campaigns) Sample Input
\{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
"field_name": "Customer Loyalty Score",
"field_type": "Number"
\}
Sample Output
{
"id": "e1a13f42-b8b2-4f99-9a54-3f68c9f8b432",
"name": "Customer Loyalty Score",
"field_type": "Number",
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/field_definitions/e1a13f42-b8b2-4f99-9a54-3f68c9f8b432"
}
}
Create list – New
Create a new list in your SendGrid account. (New Marketing Campaigns) Sample Input Sample Output
{
"name": "Newsletter Subscribers",
"id": "abc123def456ghi789",
"contact_count": 0,
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/lists/abc123def456ghi789"
}
}
Create segment – New
Create a new segment in your SendGrid account. (New Marketing Campaigns) Sample Input
{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
"segment_name": "High Value Customers",
"segment_query": {
"initial_segment_query": \{
"field": "total_spent",
"operator": ">",
"value": 1000
\},
"additional_segment_query": [
\{
"join": "AND",
"field": "last_purchase_date",
"operator": ">",
"value": "2023-01-01T00:00:00Z"
\}
]
},
"parent_list_id": "abc123def456"
}
Sample Output
{
"id": "seg_123456789",
"name": "High Value Customers",
"query_dsl": "(total_spent > 1000) AND (last_purchase_date > '2023-01-01T00:00:00Z')",
"contacts_count": 1250,
"contacts_sample": [
\{
"email": "john.doe@example.com",
"total_spent": 1500,
"last_purchase_date": "2023-03-15T14:30:00Z"
\},
\{
"email": "jane.smith@example.com",
"total_spent": 2000,
"last_purchase_date": "2023-02-28T09:45:00Z"
\}
],
"sample_updated_at": "2023-04-01T12:00:00Z",
"created_at": "2023-04-01T10:30:00Z",
"updated_at": "2023-04-01T10:30:00Z",
"parent_list_id": "abc123def456",
"query_json": "{\"and\":[\{\"field\":\"total_spent\",\"operator\":\">\",\"value\":1000\},\{\"field\":\"last_purchase_date\",\"operator\":\">\",\"value\":\"2023-01-01T00:00:00Z\"\}]}"
}
Create/update contacts - Legacy
Create or update contacts in your SendGrid contacts database. If one of the contacts you specify is different to the existing contact in SendGrid, the contact in SendGrid will be updated with the new details. (Legacy Marketing Campaigns) Sample Input Sample Output
\{
"error_count": 0,
"error_indices": [],
"new_count": 1,
"persisted_recipients": [
"john.doe@example.com",
"jane.smith@example.com"
],
"unmodified_indices": [
1
],
"updated_count": 1
\}
Create/update contacts – New
Create or update contacts in your SendGrid contacts database. If one of the contacts you specify is different to the existing contact in Sendgrid, the contact in SendGrid will be updated with the new details. (New Marketing Campaigns) Sample Input
{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"list_ids": [
"1234abcd-5678-efgh-9012-ijklmnopqrst",
"5678efgh-9012-ijkl-mnop-qrstuvwxyzab"
],
"contacts": [
{
"email": "john.doe@example.com",
"alternate_emails": [
"johnd@work.com",
"jdoe@personal.com"
],
"first_name": "John",
"last_name": "Doe",
"address_line_1": "123 Main St",
"address_line_2": "Apt 4B",
"city": "New York",
"country": "USA",
"postal_code": "10001",
"state_province_region": "NY",
"custom_fields": [
\{
"field": "e1_T",
"value": "Premium"
\},
\{
"field": "e2_N",
"value": 42
\},
\{
"field": "e3_D",
"value": "05/15/2023"
\}
]
},
\{
"email": "jane.smith@example.com",
"first_name": "Jane",
"last_name": "Smith",
"city": "London",
"country": "UK",
"postal_code": "SW1A 1AA"
\}
]
}
Sample Output
{
"result": "Successfully created or updated 2 contacts."
}
Get list - New
Return data on a specific list by ID. (New Marketing Campaigns) Sample Input
\{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
"id": "abc123def456",
"contact_sample": true
\}
Sample Output
List campaigns - Legacy
Get a list of campaigns from your SendGrid account. (Legacy Marketing Campaigns) Sample Input Sample Output
{
"result": [
\{
"id": 12345,
"title": "Summer Sale Newsletter",
"ip_pool": "marketing_pool",
"categories": [
"sales",
"summer"
],
"plain_content": "Don't miss our amazing summer sale!",
"html_content": "<h1>Summer Sale!</h1><p>Don't miss our amazing summer sale!</p>",
"subject": "Summer Sale - Up to 50% Off!",
"sender_id": null,
"list_ids": [
67890,
67891
],
"segment_ids": [
45678
],
"suppression_group_id": null,
"custom_unsubscribe_url": "https://example.com/unsubscribe",
"status": "draft",
"editor": "design"
\},
\{
"id": 12346,
"title": "Monthly Newsletter",
"ip_pool": "transactional_pool",
"categories": [
"newsletter"
],
"plain_content": "Here's what's new this month!",
"html_content": "<h1>Monthly Update</h1><p>Here's what's new this month!</p>",
"subject": "Your Monthly Update",
"sender_id": null,
"list_ids": [
67890
],
"segment_ids": [],
"suppression_group_id": null,
"custom_unsubscribe_url": "https://example.com/unsubscribe",
"status": "scheduled",
"editor": "code"
\}
]
}
List categories
Retrieve a list of all the categories in your SendGrid account. Sample Input Sample Output
List contacts - Legacy
Get a list of contacts (recipients) from your SendGrid account. (Legacy Marketing Campaigns) Sample Input
\{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"page": 1,
"per_page": 10
\}
Sample Output
List contacts - New
Get a list of contacts (recipients) from your SendGrid account. (New Marketing Campaigns) Sample Input
{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
}
Sample Output
{
"result": [
{
"address_line_1": "123 Main St",
"address_line_2": "Apt 4B",
"alternate_emails": [
"john.doe@example.com",
"jdoe@work.com"
],
"city": "New York",
"country": "United States",
"email": "johndoe@example.com",
"first_name": "John",
"id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
"last_name": "Doe",
"list_ids": [
"list1",
"list2"
],
"postal_code": "10001",
"state_province_region": "NY",
"phone_number": "+1-555-123-4567",
"whatsapp": "+1-555-987-6543",
"line": "johndoe_line",
"facebook": "johndoe.facebook",
"unique_name": "johnd",
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/contacts/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
},
"custom_fields": {},
"created_at": "2023-05-01T12:00:00Z",
"updated_at": "2023-05-15T09:30:00Z"
}
],
"contact_count": 1,
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/contacts"
}
}
List custom fields - Legacy
Get a list of all of the custom fields in your SendGrid account. (Legacy Marketing Campaigns) Sample Input
{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
}
Sample Output
{
"custom_fields": [
\{
"id": 1,
"name": "favorite_color",
"type": "text"
\},
\{
"id": 2,
"name": "birth_date",
"type": "date"
\},
\{
"id": 3,
"name": "loyalty_points",
"type": "number"
\}
]
}
List custom fields – New
Get a list of all of the custom fields in your SendGrid account. (New Marketing Campaigns) Sample Input
{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
}
Sample Output
{
"custom_fields": [
{
"id": "e1_T",
"name": "favorite_color",
"field_type": "Text",
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/field_definitions/e1_T"
}
},
{
"id": "e2_N",
"name": "age",
"field_type": "Number",
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/field_definitions/e2_N"
}
}
],
"reserved_fields": [
\{
"id": "first_name",
"name": "first_name",
"field_type": "Text",
"read_only": true
\},
\{
"id": "last_name",
"name": "last_name",
"field_type": "Text",
"read_only": true
\},
\{
"id": "email",
"name": "email",
"field_type": "Text",
"read_only": true
\}
],
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/field_definitions"
}
}
List lists - Legacy
Get a list of all of the lists in your SendGrid account. (Legacy Marketing Campaigns) Sample Input Sample Output
{
"lists": [
\{
"id": 1234,
"name": "Newsletter Subscribers",
"recipient_count": 5000
\},
\{
"id": 5678,
"name": "Product Updates",
"recipient_count": 3500
\},
\{
"id": 9012,
"name": "Event Attendees",
"recipient_count": 1200
\}
]
}
List lists - New
Get a list of all of the lists in your SendGrid account. (New Marketing Campaigns) Sample Input
\{
"api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
"page_size": 100,
"page_token": "1"
\}
Sample Output
{
"result": [
{
"name": "Newsletter Subscribers",
"id": "abc123def456",
"contact_count": 5000,
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/lists/abc123def456"
}
},
{
"name": "VIP Customers",
"id": "ghi789jkl012",
"contact_count": 1000,
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/lists/ghi789jkl012"
}
},
{
"name": "Inactive Users",
"id": "mno345pqr678",
"contact_count": 2500,
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/lists/mno345pqr678"
}
}
],
"_metadata": {
"self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=1"
}
}
List segments - New
Get a list of segments in your SendGrid account. (New Marketing Campaigns) Sample Input Sample Output
{
"results": [
\{
"id": "segment_001",
"name": "Active Customers",
"contacts_count": 5000,
"sample_updated_at": "2023-05-15T14:30:00Z",
"created_at": "2023-01-01T10:00:00Z",
"updated_at": "2023-05-15T14:30:00Z",
"parent_list_id": "list_123"
\},
\{
"id": "segment_002",
"name": "High-Value Customers",
"contacts_count": 1000,
"sample_updated_at": "2023-05-14T09:15:00Z",
"created_at": "2023-02-15T11:30:00Z",
"updated_at": "2023-05-14T09:15:00Z",
"parent_list_id": "list_456"
\}
]
}
Raw HTTP request (advanced)
Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication. Sample Input
{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"method": "POST",
"url": {
"endpoint": "/v3/mail/send"
},
"headers": [
\{
"key": "Content-Type",
"value": "application/json"
\}
],
"body": {
"raw": {
"personalizations": [
{
"to": [
{
"email": "recipient@example.com"
}
],
"subject": "Hello from SendGrid"
}
],
"from": {
"email": "sender@example.com"
},
"content": [
\{
"type": "text/plain",
"value": "This is a test email sent using SendGrid API."
\}
]
}
},
"include_raw_body": true,
"parse_response": "true"
}
Sample Output
{
"response": {
"status_code": 202,
"headers": \{
"server": "nginx",
"date": "Mon, 01 May 2023 12:00:00 GMT",
"content-length": "0",
"connection": "keep-alive",
"x-message-id": "14c5d75ce93.dfd.64567890",
"access-control-allow-origin": "https://sendgrid.api-docs.io",
"access-control-allow-methods": "POST",
"access-control-allow-headers": "Authorization, Content-Type, On-behalf-of, x-sg-elas-acl",
"access-control-max-age": "600",
"x-no-cors-reason": "https://sendgrid.com/docs/Classroom/Basics/API/cors.html",
"strict-transport-security": "max-age=600; includeSubDomains"
\},
"body": ""
}
}
Search contacts - Legacy
Search for contacts in your SendGrid account, based on one or more criteria. (Legacy Marketing Campaigns) Sample Input
{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"conditions": [
\{
"field": "email",
"operator": "contains",
"value": "@example.com"
\},
\{
"field": "first_name",
"operator": "not_empty"
\}
],
"list_id": 12345
}
Sample Output
Send Email
Send an email to up to 1,000 people via SendGrid. Sample Input
{
"api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"subject": "Important Update: Team Meeting",
"content": "<html><body><h1>Team Meeting Reminder</h1><p>Dear %name%,</p><p>This is a reminder that our team meeting is scheduled for %meeting_date% at %meeting_time%.</p><p>Please come prepared to discuss your current projects.</p><p>Best regards,<br>The Management Team</p></body></html>",
"personalizations": [
{
"to": [
\{
"email": "john.doe@example.com",
"name": "John Doe"
\},
\{
"email": "jane.smith@example.com",
"name": "Jane Smith"
\}
],
"cc": [
\{
"email": "manager@example.com",
"name": "Team Manager"
\}
],
"substitutions": \{
"%name%": "John",
"%meeting_date%": "May 15, 2023",
"%meeting_time%": "2:00 PM EST"
\}
},
{
"to": [
\{
"email": "alice.johnson@example.com",
"name": "Alice Johnson"
\}
],
"substitutions": \{
"%name%": "Alice",
"%meeting_date%": "May 15, 2023",
"%meeting_time%": "2:00 PM EST"
\}
}
],
"from": \{
"email": "notifications@company.com",
"name": "Company Notifications"
\},
"reply_to": \{
"email": "support@company.com",
"name": "Company Support"
\},
"categories": [
"Team Communication",
"Meetings"
],
"unsubscribe_group_id": 12345
}
Sample Output
{
"result": "success"
}
DDL operations
List custom fields (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
[
\{
"id": "e1_T",
"name": "first_name",
"field_type": "text"
\},
\{
"id": "e2_N",
"name": "last_name",
"field_type": "text"
\},
\{
"id": "e3_D",
"name": "birth_date",
"field_type": "date"
\},
\{
"id": "e4_N",
"name": "loyalty_points",
"field_type": "number"
\}
]
List custom fields new (DDL)
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
{
"custom_fields": [
\{
"id": "e1_T",
"name": "first_name",
"type": "text",
"field_type": "text"
\},
\{
"id": "e2_N",
"name": "last_name",
"type": "text",
"field_type": "text"
\},
\{
"id": "e3_D",
"name": "birth_date",
"type": "date",
"field_type": "date"
\},
\{
"id": "e4_N",
"name": "loyalty_points",
"type": "number",
"field_type": "number"
\}
]
}
List lists (DDL)
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
[
\{
"id": "1234567",
"name": "Newsletter Subscribers",
"recipient_count": 5000
\},
\{
"id": "2345678",
"name": "Product Updates",
"recipient_count": 3500
\},
\{
"id": "3456789",
"name": "VIP Customers",
"recipient_count": 1000
\}
]
List lists new (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
{
"result": [
\{
"id": "1234567",
"name": "Newsletter Subscribers",
"contact_count": 5000,
"created_at": "2023-05-15T10:30:00Z",
"updated_at": "2023-06-01T14:45:00Z"
\},
\{
"id": "7654321",
"name": "Product Updates",
"contact_count": 3500,
"created_at": "2023-04-20T09:15:00Z",
"updated_at": "2023-05-28T11:20:00Z"
\},
\{
"id": "9876543",
"name": "Event Attendees",
"contact_count": 1200,
"created_at": "2023-05-01T16:00:00Z",
"updated_at": "2023-05-30T08:10:00Z"
\}
]
}
List reserved fields (DDL)
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
{
"reserved_fields": [
\{
"name": "email",
"type": "text"
\},
\{
"name": "first_name",
"type": "text"
\},
\{
"name": "last_name",
"type": "text"
\},
\{
"name": "created_at",
"type": "date"
\},
\{
"name": "last_emailed",
"type": "date"
\},
\{
"name": "last_clicked",
"type": "date"
\},
\{
"name": "last_opened",
"type": "date"
\},
\{
"name": "unsubscribed",
"type": "boolean"
\}
]
}
List searchable fields (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
List searchable fields new (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
\{
"searchable_fields": [
"email",
"first_name",
"last_name",
"address_line_1",
"address_line_2",
"city",
"state_province_region",
"postal_code",
"country",
"phone_number",
"whatsapp",
"line",
"facebook",
"unique_name",
"custom_fields"
]
\}
List templates (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input Sample Output
[
{
"id": "d-123abc456def7890ghij",
"name": "Welcome Email",
"generation": "dynamic",
"updated_at": "2023-05-15T10:30:00Z",
"versions": [
\{
"id": "v-123abc456def7890ghij",
"name": "Version 1",
"subject": "Welcome to Our Service!",
"updated_at": "2023-05-15T10:30:00Z",
"active": 1
\}
]
},
{
"id": "d-234bcd567efg8901hijk",
"name": "Monthly Newsletter",
"generation": "legacy",
"updated_at": "2023-05-10T14:45:00Z",
"versions": [
\{
"id": "v-234bcd567efg8901hijk",
"name": "May Edition",
"subject": "Your May Newsletter Is Here",
"updated_at": "2023-05-10T14:45:00Z",
"active": 1
\}
]
}
]
List unsubscribe groups (DDL)
Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping
Sample Input
{
"api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
Sample Output
[
\{
"id": 103,
"name": "Newsletter",
"description": "Daily newsletter updates",
"is_default": false
\},
\{
"id": 104,
"name": "Promotional Emails",
"description": "Special offers and promotions",
"is_default": true
\},
\{
"id": 105,
"name": "Product Updates",
"description": "Information about new features and releases",
"is_default": false
\}
]