Go to appAcademyWhat's new?
Back
Artisan IMG > SendGrid (sendgrid) (b3753df1-d7e1-4bca-bd9d-7b83afcc209e)
Sendgrid
OverviewOperations (sample payloads)Operations

Operations (sample payloads)

Main operations
Copy

Add contacts to list - Legacy
Copy

Add up to 1,000 contacts in your SendGrid database to a list in SendGrid. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "list_id": 12345,
4
    "contact_ids": [
5
        "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
6
        "b2c3d4e5-f6g7-8h9i-0j1k-l2m3n4o5p6q7",
7
        "c3d4e5f6-g7h8-9i0j-1k2l-m3n4o5p6q7r8"
8
    ]
9
}

Sample Output

1
{
2
    "success": true
3
}

Create custom field – New
Copy

Create a new custom field in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "field_name": "Customer Loyalty Score",
4
    "field_type": "Number"
5
}

Sample Output

1
{
2
    "id": "e1a13f42-b8b2-4f99-9a54-3f68c9f8b432",
3
    "name": "Customer Loyalty Score",
4
    "field_type": "Number",
5
    "_metadata": {
6
        "self": "https://api.sendgrid.com/v3/marketing/field_definitions/e1a13f42-b8b2-4f99-9a54-3f68c9f8b432"
7
    }
8
}

Create list – New
Copy

Create a new list in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "list_name": "Newsletter Subscribers"
4
}

Sample Output

1
{
2
    "name": "Newsletter Subscribers",
3
    "id": "abc123def456ghi789",
4
    "contact_count": 0,
5
    "_metadata": {
6
        "self": "https://api.sendgrid.com/v3/marketing/lists/abc123def456ghi789"
7
    }
8
}

Create segment – New
Copy

Create a new segment in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "segment_name": "High Value Customers",
4
    "segment_query": {
5
        "initial_segment_query": {
6
            "field": "total_spent",
7
            "operator": ">",
8
            "value": 1000
9
        },
10
        "additional_segment_query": [
11
            {
12
                "join": "AND",
13
                "field": "last_purchase_date",
14
                "operator": ">",
15
                "value": "2023-01-01T00:00:00Z"
16
            }
17
        ]
18
    },
19
    "parent_list_id": "abc123def456"
20
}

Sample Output

1
{
2
    "id": "seg_123456789",
3
    "name": "High Value Customers",
4
    "query_dsl": "(total_spent > 1000) AND (last_purchase_date > '2023-01-01T00:00:00Z')",
5
    "contacts_count": 1250,
6
    "contacts_sample": [
7
        {
8
            "email": "john.doe@example.com",
9
            "total_spent": 1500,
10
            "last_purchase_date": "2023-03-15T14:30:00Z"
11
        },
12
        {
13
            "email": "jane.smith@example.com",
14
            "total_spent": 2000,
15
            "last_purchase_date": "2023-02-28T09:45:00Z"
16
        }
17
    ],
18
    "sample_updated_at": "2023-04-01T12:00:00Z",
19
    "created_at": "2023-04-01T10:30:00Z",
20
    "updated_at": "2023-04-01T10:30:00Z",
21
    "parent_list_id": "abc123def456",
22
    "query_json": "{\"and\":[{\"field\":\"total_spent\",\"operator\":\">\",\"value\":1000},{\"field\":\"last_purchase_date\",\"operator\":\">\",\"value\":\"2023-01-01T00:00:00Z\"}]}"
23
}

Create/update contacts - Legacy
Copy

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

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "contacts": [
4
        {
5
            "email": "john.doe@example.com",
6
            "first_name": "John",
7
            "last_name": "Doe",
8
            "custom_fields": [
9
                {
10
                    "field": "Company",
11
                    "value": "Acme Corp"
12
                },
13
                {
14
                    "field": "Age",
15
                    "value": 35
16
                }
17
            ]
18
        },
19
        {
20
            "email": "jane.smith@example.com",
21
            "first_name": "Jane",
22
            "last_name": "Smith",
23
            "custom_fields": [
24
                {
25
                    "field": "Company",
26
                    "value": "XYZ Inc"
27
                },
28
                {
29
                    "field": "Subscription_Status",
30
                    "value": "Active"
31
                }
32
            ]
33
        }
34
    ]
35
}

Sample Output

1
{
2
    "error_count": 0,
3
    "error_indices": [],
4
    "new_count": 1,
5
    "persisted_recipients": [
6
        "john.doe@example.com",
7
        "jane.smith@example.com"
8
    ],
9
    "unmodified_indices": [
10
        1
11
    ],
12
    "updated_count": 1
13
}

Create/update contacts – New
Copy

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

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "list_ids": [
4
        "1234abcd-5678-efgh-9012-ijklmnopqrst",
5
        "5678efgh-9012-ijkl-mnop-qrstuvwxyzab"
6
    ],
7
    "contacts": [
8
        {
9
            "email": "john.doe@example.com",
10
            "alternate_emails": [
11
                "johnd@work.com",
12
                "jdoe@personal.com"
13
            ],
14
            "first_name": "John",
15
            "last_name": "Doe",
16
            "address_line_1": "123 Main St",
17
            "address_line_2": "Apt 4B",
18
            "city": "New York",
19
            "country": "USA",
20
            "postal_code": "10001",
21
            "state_province_region": "NY",
22
            "custom_fields": [
23
                {
24
                    "field": "e1_T",
25
                    "value": "Premium"
26
                },
27
                {
28
                    "field": "e2_N",
29
                    "value": 42
30
                },
31
                {
32
                    "field": "e3_D",
33
                    "value": "05/15/2023"
34
                }
35
            ]
36
        },
37
        {
38
            "email": "jane.smith@example.com",
39
            "first_name": "Jane",
40
            "last_name": "Smith",
41
            "city": "London",
42
            "country": "UK",
43
            "postal_code": "SW1A 1AA"
44
        }
45
    ]
46
}

Sample Output

1
{
2
    "result": "Successfully created or updated 2 contacts."
3
}

Get list - New
Copy

Return data on a specific list by ID. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "id": "abc123def456",
4
    "contact_sample": true
5
}

Sample Output

1
{
2
    "name": "Newsletter Subscribers",
3
    "id": "abc123def456",
4
    "contact_count": 1500,
5
    "contact_sample": [
6
        {
7
            "address_line_1": "123 Main St",
8
            "address_line_2": "Apt 4B",
9
            "alternate_emails": [
10
                "john.doe@example.com",
11
                "jdoe@work.com"
12
            ],
13
            "city": "New York",
14
            "country": "USA",
15
            "email": "johndoe@example.com",
16
            "first_name": "John",
17
            "id": "contact123",
18
            "last_name": "Doe",
19
            "list_ids": [
20
                "abc123def456",
21
                "ghi789jkl012"
22
            ],
23
            "postal_code": "10001",
24
            "state_province_region": "NY",
25
            "phone_number": "+1-555-123-4567",
26
            "whatsapp": "+1-555-987-6543",
27
            "line": "johndoe_line",
28
            "facebook": "johndoe.facebook",
29
            "unique_name": "johnd",
30
            "_metadata": {
31
                "self": "https://api.sendgrid.com/v3/marketing/contacts/contact123"
32
            },
33
            "custom_fields": {
34
                "bird": "sparrow",
35
                "cloud": "cumulus",
36
                "tree": 42
37
            },
38
            "created_at": "2023-04-15T10:30:00Z",
39
            "updated_at": "2023-04-20T15:45:00Z"
40
        }
41
    ],
42
    "_metadata": {
43
        "self": "https://api.sendgrid.com/v3/marketing/lists/abc123def456"
44
    }
45
}

List campaigns - Legacy
Copy

Get a list of campaigns from your SendGrid account. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "page": 1,
4
    "per_page": 10
5
}

Sample Output

1
{
2
    "result": [
3
        {
4
            "id": 12345,
5
            "title": "Summer Sale Newsletter",
6
            "ip_pool": "marketing_pool",
7
            "categories": [
8
                "sales",
9
                "summer"
10
            ],
11
            "plain_content": "Don't miss our amazing summer sale!",
12
            "html_content": "<h1>Summer Sale!</h1><p>Don't miss our amazing summer sale!</p>",
13
            "subject": "Summer Sale - Up to 50% Off!",
14
            "sender_id": null,
15
            "list_ids": [
16
                67890,
17
                67891
18
            ],
19
            "segment_ids": [
20
                45678
21
            ],
22
            "suppression_group_id": null,
23
            "custom_unsubscribe_url": "https://example.com/unsubscribe",
24
            "status": "draft",
25
            "editor": "design"
26
        },
27
        {
28
            "id": 12346,
29
            "title": "Monthly Newsletter",
30
            "ip_pool": "transactional_pool",
31
            "categories": [
32
                "newsletter"
33
            ],
34
            "plain_content": "Here's what's new this month!",
35
            "html_content": "<h1>Monthly Update</h1><p>Here's what's new this month!</p>",
36
            "subject": "Your Monthly Update",
37
            "sender_id": null,
38
            "list_ids": [
39
                67890
40
            ],
41
            "segment_ids": [],
42
            "suppression_group_id": null,
43
            "custom_unsubscribe_url": "https://example.com/unsubscribe",
44
            "status": "scheduled",
45
            "editor": "code"
46
        }
47
    ]
48
}

List categories
Copy

Retrieve a list of all the categories in your SendGrid account.

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "category": "newsletter",
4
    "limit": 10,
5
    "page": 1
6
}

Sample Output

1
{
2
    "results": [
3
        {
4
            "category": "newsletter_weekly"
5
        },
6
        {
7
            "category": "newsletter_monthly"
8
        },
9
        {
10
            "category": "newsletter_special"
11
        },
12
        {
13
            "category": "newsletter_promo"
14
        },
15
        {
16
            "category": "newsletter_update"
17
        }
18
    ]
19
}

List contacts - Legacy
Copy

Get a list of contacts (recipients) from your SendGrid account. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "page": 1,
4
    "per_page": 10
5
}

Sample Output

1
{
2
    "recipients": [
3
        {
4
            "created_at": 1623456789,
5
            "custom_fields": [
6
                {
7
                    "id": 1,
8
                    "name": "Company",
9
                    "type": "text",
10
                    "value": null
11
                },
12
                {
13
                    "id": 2,
14
                    "name": "Industry",
15
                    "type": "text",
16
                    "value": null
17
                }
18
            ],
19
            "email": "john.doe@example.com",
20
            "first_name": "John",
21
            "id": "abc123def456",
22
            "last_clicked": null,
23
            "last_emailed": null,
24
            "last_name": "Doe",
25
            "last_opened": null,
26
            "updated_at": 1623456789
27
        },
28
        {
29
            "created_at": 1623457890,
30
            "custom_fields": [
31
                {
32
                    "id": 1,
33
                    "name": "Company",
34
                    "type": "text",
35
                    "value": null
36
                },
37
                {
38
                    "id": 2,
39
                    "name": "Industry",
40
                    "type": "text",
41
                    "value": null
42
                }
43
            ],
44
            "email": "jane.smith@example.com",
45
            "first_name": "Jane",
46
            "id": "ghi789jkl012",
47
            "last_clicked": null,
48
            "last_emailed": null,
49
            "last_name": "Smith",
50
            "last_opened": null,
51
            "updated_at": 1623457890
52
        }
53
    ]
54
}

List contacts - New
Copy

Get a list of contacts (recipients) from your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
3
}

Sample Output

1
{
2
    "result": [
3
        {
4
            "address_line_1": "123 Main St",
5
            "address_line_2": "Apt 4B",
6
            "alternate_emails": [
7
                "john.doe@example.com",
8
                "jdoe@work.com"
9
            ],
10
            "city": "New York",
11
            "country": "United States",
12
            "email": "johndoe@example.com",
13
            "first_name": "John",
14
            "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
15
            "last_name": "Doe",
16
            "list_ids": [
17
                "list1",
18
                "list2"
19
            ],
20
            "postal_code": "10001",
21
            "state_province_region": "NY",
22
            "phone_number": "+1-555-123-4567",
23
            "whatsapp": "+1-555-987-6543",
24
            "line": "johndoe_line",
25
            "facebook": "johndoe.facebook",
26
            "unique_name": "johnd",
27
            "_metadata": {
28
                "self": "https://api.sendgrid.com/v3/marketing/contacts/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
29
            },
30
            "custom_fields": {},
31
            "created_at": "2023-05-01T12:00:00Z",
32
            "updated_at": "2023-05-15T09:30:00Z"
33
        }
34
    ],
35
    "contact_count": 1,
36
    "_metadata": {
37
        "self": "https://api.sendgrid.com/v3/marketing/contacts"
38
    }
39
}

List custom fields - Legacy
Copy

Get a list of all of the custom fields in your SendGrid account. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
3
}

Sample Output

1
{
2
    "custom_fields": [
3
        {
4
            "id": 1,
5
            "name": "favorite_color",
6
            "type": "text"
7
        },
8
        {
9
            "id": 2,
10
            "name": "birth_date",
11
            "type": "date"
12
        },
13
        {
14
            "id": 3,
15
            "name": "loyalty_points",
16
            "type": "number"
17
        }
18
    ]
19
}

List custom fields – New
Copy

Get a list of all of the custom fields in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
3
}

Sample Output

1
{
2
    "custom_fields": [
3
        {
4
            "id": "e1_T",
5
            "name": "favorite_color",
6
            "field_type": "Text",
7
            "_metadata": {
8
                "self": "https://api.sendgrid.com/v3/marketing/field_definitions/e1_T"
9
            }
10
        },
11
        {
12
            "id": "e2_N",
13
            "name": "age",
14
            "field_type": "Number",
15
            "_metadata": {
16
                "self": "https://api.sendgrid.com/v3/marketing/field_definitions/e2_N"
17
            }
18
        }
19
    ],
20
    "reserved_fields": [
21
        {
22
            "id": "first_name",
23
            "name": "first_name",
24
            "field_type": "Text",
25
            "read_only": true
26
        },
27
        {
28
            "id": "last_name",
29
            "name": "last_name",
30
            "field_type": "Text",
31
            "read_only": true
32
        },
33
        {
34
            "id": "email",
35
            "name": "email",
36
            "field_type": "Text",
37
            "read_only": true
38
        }
39
    ],
40
    "_metadata": {
41
        "self": "https://api.sendgrid.com/v3/marketing/field_definitions"
42
    }
43
}

List lists - Legacy
Copy

Get a list of all of the lists in your SendGrid account. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz"
3
}

Sample Output

1
{
2
    "lists": [
3
        {
4
            "id": 1234,
5
            "name": "Newsletter Subscribers",
6
            "recipient_count": 5000
7
        },
8
        {
9
            "id": 5678,
10
            "name": "Product Updates",
11
            "recipient_count": 3500
12
        },
13
        {
14
            "id": 9012,
15
            "name": "Event Attendees",
16
            "recipient_count": 1200
17
        }
18
    ]
19
}

List lists - New
Copy

Get a list of all of the lists in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "page_size": 100,
4
    "page_token": "1"
5
}

Sample Output

1
{
2
    "result": [
3
        {
4
            "name": "Newsletter Subscribers",
5
            "id": "abc123def456",
6
            "contact_count": 5000,
7
            "_metadata": {
8
                "self": "https://api.sendgrid.com/v3/marketing/lists/abc123def456"
9
            }
10
        },
11
        {
12
            "name": "VIP Customers",
13
            "id": "ghi789jkl012",
14
            "contact_count": 1000,
15
            "_metadata": {
16
                "self": "https://api.sendgrid.com/v3/marketing/lists/ghi789jkl012"
17
            }
18
        },
19
        {
20
            "name": "Inactive Users",
21
            "id": "mno345pqr678",
22
            "contact_count": 2500,
23
            "_metadata": {
24
                "self": "https://api.sendgrid.com/v3/marketing/lists/mno345pqr678"
25
            }
26
        }
27
    ],
28
    "_metadata": {
29
        "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=1"
30
    }
31
}

List segments - New
Copy

Get a list of segments in your SendGrid account. (New Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.1234567890abcdefghijklmnopqrstuvwxyz",
3
    "parent_list_ids": [
4
        "list_123",
5
        "list_456"
6
    ],
7
    "no_parent_list_id": false
8
}

Sample Output

1
{
2
    "results": [
3
        {
4
            "id": "segment_001",
5
            "name": "Active Customers",
6
            "contacts_count": 5000,
7
            "sample_updated_at": "2023-05-15T14:30:00Z",
8
            "created_at": "2023-01-01T10:00:00Z",
9
            "updated_at": "2023-05-15T14:30:00Z",
10
            "parent_list_id": "list_123"
11
        },
12
        {
13
            "id": "segment_002",
14
            "name": "High-Value Customers",
15
            "contacts_count": 1000,
16
            "sample_updated_at": "2023-05-14T09:15:00Z",
17
            "created_at": "2023-02-15T11:30:00Z",
18
            "updated_at": "2023-05-14T09:15:00Z",
19
            "parent_list_id": "list_456"
20
        }
21
    ]
22
}

Raw HTTP request (advanced)
Copy

Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication.

Sample Input

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "method": "POST",
4
    "url": {
5
        "endpoint": "/v3/mail/send"
6
    },
7
    "headers": [
8
        {
9
            "key": "Content-Type",
10
            "value": "application/json"
11
        }
12
    ],
13
    "body": {
14
        "raw": {
15
            "personalizations": [
16
                {
17
                    "to": [
18
                        {
19
                            "email": "recipient@example.com"
20
                        }
21
                    ],
22
                    "subject": "Hello from SendGrid"
23
                }
24
            ],
25
            "from": {
26
                "email": "sender@example.com"
27
            },
28
            "content": [
29
                {
30
                    "type": "text/plain",
31
                    "value": "This is a test email sent using SendGrid API."
32
                }
33
            ]
34
        }
35
    },
36
    "include_raw_body": true,
37
    "parse_response": "true"
38
}

Sample Output

1
{
2
    "response": {
3
        "status_code": 202,
4
        "headers": {
5
            "server": "nginx",
6
            "date": "Mon, 01 May 2023 12:00:00 GMT",
7
            "content-length": "0",
8
            "connection": "keep-alive",
9
            "x-message-id": "14c5d75ce93.dfd.64567890",
10
            "access-control-allow-origin": "https://sendgrid.api-docs.io",
11
            "access-control-allow-methods": "POST",
12
            "access-control-allow-headers": "Authorization, Content-Type, On-behalf-of, x-sg-elas-acl",
13
            "access-control-max-age": "600",
14
            "x-no-cors-reason": "https://sendgrid.com/docs/Classroom/Basics/API/cors.html",
15
            "strict-transport-security": "max-age=600; includeSubDomains"
16
        },
17
        "body": ""
18
    }
19
}

Search contacts - Legacy
Copy

Search for contacts in your SendGrid account, based on one or more criteria. (Legacy Marketing Campaigns)

Sample Input

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "conditions": [
4
        {
5
            "field": "email",
6
            "operator": "contains",
7
            "value": "@example.com"
8
        },
9
        {
10
            "field": "first_name",
11
            "operator": "not_empty"
12
        }
13
    ],
14
    "list_id": 12345
15
}

Sample Output

1
{
2
    "contact_count": 2,
3
    "contacts": [
4
        {
5
            "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
6
            "email": "john.doe@example.com",
7
            "first_name": "John",
8
            "last_name": "Doe",
9
            "created_at": "2023-04-15T10:30:00Z",
10
            "updated_at": "2023-04-15T10:30:00Z",
11
            "custom_fields": {
12
                "company": "Acme Inc.",
13
                "role": "Developer"
14
            }
15
        },
16
        {
17
            "id": "b2c3d4e5-f6g7-8901-h2i3-j4k5l6m7n8o9",
18
            "email": "jane.smith@example.com",
19
            "first_name": "Jane",
20
            "last_name": "Smith",
21
            "created_at": "2023-04-14T15:45:00Z",
22
            "updated_at": "2023-04-14T15:45:00Z",
23
            "custom_fields": {
24
                "company": "XYZ Corp",
25
                "role": "Manager"
26
            }
27
        }
28
    ]
29
}

Send Email
Copy

Send an email to up to 1,000 people via SendGrid.

Sample Input

1
{
2
    "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3
    "subject": "Important Update: Team Meeting",
4
    "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>",
5
    "personalizations": [
6
        {
7
            "to": [
8
                {
9
                    "email": "john.doe@example.com",
10
                    "name": "John Doe"
11
                },
12
                {
13
                    "email": "jane.smith@example.com",
14
                    "name": "Jane Smith"
15
                }
16
            ],
17
            "cc": [
18
                {
19
                    "email": "manager@example.com",
20
                    "name": "Team Manager"
21
                }
22
            ],
23
            "substitutions": {
24
                "%name%": "John",
25
                "%meeting_date%": "May 15, 2023",
26
                "%meeting_time%": "2:00 PM EST"
27
            }
28
        },
29
        {
30
            "to": [
31
                {
32
                    "email": "alice.johnson@example.com",
33
                    "name": "Alice Johnson"
34
                }
35
            ],
36
            "substitutions": {
37
                "%name%": "Alice",
38
                "%meeting_date%": "May 15, 2023",
39
                "%meeting_time%": "2:00 PM EST"
40
            }
41
        }
42
    ],
43
    "from": {
44
        "email": "notifications@company.com",
45
        "name": "Company Notifications"
46
    },
47
    "reply_to": {
48
        "email": "support@company.com",
49
        "name": "Company Support"
50
    },
51
    "categories": [
52
        "Team Communication",
53
        "Meetings"
54
    ],
55
    "unsubscribe_group_id": 12345
56
}

Sample Output

1
{
2
    "result": "success"
3
}

DDL operations
Copy

List custom fields (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
[
2
    {
3
        "id": "e1_T",
4
        "name": "first_name",
5
        "field_type": "text"
6
    },
7
    {
8
        "id": "e2_N",
9
        "name": "last_name",
10
        "field_type": "text"
11
    },
12
    {
13
        "id": "e3_D",
14
        "name": "birth_date",
15
        "field_type": "date"
16
    },
17
    {
18
        "id": "e4_N",
19
        "name": "loyalty_points",
20
        "field_type": "number"
21
    }
22
]

List custom fields new (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
{
2
    "custom_fields": [
3
        {
4
            "id": "e1_T",
5
            "name": "first_name",
6
            "type": "text",
7
            "field_type": "text"
8
        },
9
        {
10
            "id": "e2_N",
11
            "name": "last_name",
12
            "type": "text",
13
            "field_type": "text"
14
        },
15
        {
16
            "id": "e3_D",
17
            "name": "birth_date",
18
            "type": "date",
19
            "field_type": "date"
20
        },
21
        {
22
            "id": "e4_N",
23
            "name": "loyalty_points",
24
            "type": "number",
25
            "field_type": "number"
26
        }
27
    ]
28
}

List lists (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
[
2
    {
3
        "id": "1234567",
4
        "name": "Newsletter Subscribers",
5
        "recipient_count": 5000
6
    },
7
    {
8
        "id": "2345678",
9
        "name": "Product Updates",
10
        "recipient_count": 3500
11
    },
12
    {
13
        "id": "3456789",
14
        "name": "VIP Customers",
15
        "recipient_count": 1000
16
    }
17
]

List lists new (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
{
2
    "result": [
3
        {
4
            "id": "1234567",
5
            "name": "Newsletter Subscribers",
6
            "contact_count": 5000,
7
            "created_at": "2023-05-15T10:30:00Z",
8
            "updated_at": "2023-06-01T14:45:00Z"
9
        },
10
        {
11
            "id": "7654321",
12
            "name": "Product Updates",
13
            "contact_count": 3500,
14
            "created_at": "2023-04-20T09:15:00Z",
15
            "updated_at": "2023-05-28T11:20:00Z"
16
        },
17
        {
18
            "id": "9876543",
19
            "name": "Event Attendees",
20
            "contact_count": 1200,
21
            "created_at": "2023-05-01T16:00:00Z",
22
            "updated_at": "2023-05-30T08:10:00Z"
23
        }
24
    ]
25
}

List reserved fields (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
{
2
    "reserved_fields": [
3
        {
4
            "name": "email",
5
            "type": "text"
6
        },
7
        {
8
            "name": "first_name",
9
            "type": "text"
10
        },
11
        {
12
            "name": "last_name",
13
            "type": "text"
14
        },
15
        {
16
            "name": "created_at",
17
            "type": "date"
18
        },
19
        {
20
            "name": "last_emailed",
21
            "type": "date"
22
        },
23
        {
24
            "name": "last_clicked",
25
            "type": "date"
26
        },
27
        {
28
            "name": "last_opened",
29
            "type": "date"
30
        },
31
        {
32
            "name": "unsubscribed",
33
            "type": "boolean"
34
        }
35
    ]
36
}

List searchable fields (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
{
2
    "searchable_fields": [
3
        "from_email",
4
        "to_email",
5
        "subject",
6
        "status",
7
        "date_sent",
8
        "msg_id",
9
        "category"
10
    ]
11
}

List searchable fields new (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mNoPqRsTuVwXyZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
{
2
    "searchable_fields": [
3
        "email",
4
        "first_name",
5
        "last_name",
6
        "address_line_1",
7
        "address_line_2",
8
        "city",
9
        "state_province_region",
10
        "postal_code",
11
        "country",
12
        "phone_number",
13
        "whatsapp",
14
        "line",
15
        "facebook",
16
        "unique_name",
17
        "custom_fields"
18
    ]
19
}

List templates (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
[
2
    {
3
        "id": "d-123abc456def7890ghij",
4
        "name": "Welcome Email",
5
        "generation": "dynamic",
6
        "updated_at": "2023-05-15T10:30:00Z",
7
        "versions": [
8
            {
9
                "id": "v-123abc456def7890ghij",
10
                "name": "Version 1",
11
                "subject": "Welcome to Our Service!",
12
                "updated_at": "2023-05-15T10:30:00Z",
13
                "active": 1
14
            }
15
        ]
16
    },
17
    {
18
        "id": "d-234bcd567efg8901hijk",
19
        "name": "Monthly Newsletter",
20
        "generation": "legacy",
21
        "updated_at": "2023-05-10T14:45:00Z",
22
        "versions": [
23
            {
24
                "id": "v-234bcd567efg8901hijk",
25
                "name": "May Edition",
26
                "subject": "Your May Newsletter Is Here",
27
                "updated_at": "2023-05-10T14:45:00Z",
28
                "active": 1
29
            }
30
        ]
31
    }
32
]

List unsubscribe groups (DDL)
Copy

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

1
{
2
    "api_key": "SG.1234abcd5678efgh9012ijkl.mnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
3
}

Sample Output

1
[
2
    {
3
        "id": 103,
4
        "name": "Newsletter",
5
        "description": "Daily newsletter updates",
6
        "is_default": false
7
    },
8
    {
9
        "id": 104,
10
        "name": "Promotional Emails",
11
        "description": "Special offers and promotions",
12
        "is_default": true
13
    },
14
    {
15
        "id": 105,
16
        "name": "Product Updates",
17
        "description": "Information about new features and releases",
18
        "is_default": false
19
    }
20
]
Previous

Overview

Next

Operations