How to Automate Shopify Customer Emails using the API

Understanding Shopify Customer Emails via the API

Setting Up Shopify API Authentication for Customer Emails

This automation needs read access to customer data and the ability to update email marketing consent. Create a custom app via the Shopify Dev Dashboard with `read_customers` and `write_customers` scopes. You will also need an API key from your ESP (SendGrid, Resend, etc.) stored separately in environment variables.

1. 1Go to dev.shopify.com and log in with your Partner account.
2. 2Click 'Create app', choose 'Custom app' for single-store automation.
3. 3Under 'Admin API access scopes', enable: read_customers, write_customers, read_orders.
4. 4Click 'Save', then 'Install app' and copy the generated access token.
5. 5Store Shopify token in environment variable: export SHOPIFY_ACCESS_TOKEN='shpat_...'
6. 6Also store your ESP API key: export SENDGRID_API_KEY='SG...'
7. 7Register webhooks for customers/create and orders/create via the `webhookSubscriptionCreate` GraphQL mutation.

1import os
2import requests
3
4SHOP_DOMAIN = os.environ['SHOPIFY_SHOP_DOMAIN']
5ACCESS_TOKEN = os.environ['SHOPIFY_ACCESS_TOKEN']
6
7GRAPHQL_URL = f'https://{SHOP_DOMAIN}/admin/api/2026-04/graphql.json'
8HEADERS = {
9    'X-Shopify-Access-Token': ACCESS_TOKEN,
10    'Content-Type': 'application/json',
11}
12
13# Test: fetch first 3 customers
14query = '{ customers(first: 3) { edges { node { id email displayName emailMarketingConsent { marketingState } } } } }'
15resp = requests.post(GRAPHQL_URL, json={'query': query}, headers=HEADERS)
16print(resp.json())

Key endpoints

1{"query": "{ customers(first: 50, query: \"tag:vip AND email_marketing_consent_state:subscribed\") { edges { node { id email displayName tags numberOfOrders totalSpentV2 { amount currencyCode } emailMarketingConsent { marketingState } } } pageInfo { hasNextPage endCursor } } }"}

1{"data": {"customers": {"edges": [{"node": {"id": "gid://shopify/Customer/11223344", "email": "jane@example.com", "displayName": "Jane Smith", "tags": ["vip"], "numberOfOrders": 12, "totalSpentV2": {"amount": "458.75", "currencyCode": "USD"}, "emailMarketingConsent": {"marketingState": "SUBSCRIBED"}}}], "pageInfo": {"hasNextPage": false}}}}

1{"query": "mutation customerEmailMarketingConsentUpdate($input: CustomerEmailMarketingConsentUpdateInput!) { customerEmailMarketingConsentUpdate(input: $input) { customer { id emailMarketingConsent { marketingState } } userErrors { field message } } }", "variables": {"input": {"customerId": "gid://shopify/Customer/11223344", "emailMarketingConsent": {"marketingState": "SUBSCRIBED", "marketingOptInLevel": "SINGLE_OPT_IN", "consentUpdatedAt": "2026-04-15T10:00:00Z"}}}}

1{"data": {"customerEmailMarketingConsentUpdate": {"customer": {"id": "gid://shopify/Customer/11223344", "emailMarketingConsent": {"marketingState": "SUBSCRIBED"}}, "userErrors": []}}}

1{"query": "mutation { webhookSubscriptionCreate(topic: CUSTOMERS_CREATE, webhookSubscription: {callbackUrl: \"https://yourapp.com/webhooks/customers-create\", format: JSON}) { userErrors { field message } webhookSubscription { id } } }"}

1{"data": {"webhookSubscriptionCreate": {"userErrors": [], "webhookSubscription": {"id": "gid://shopify/WebhookSubscription/445566"}}}}

Step-by-step automation

1# Register customers/create webhook
2curl -X POST 'https://mystore.myshopify.com/admin/api/2026-04/graphql.json' \
3  -H 'X-Shopify-Access-Token: shpat_your_token' \
4  -H 'Content-Type: application/json' \
5  -d '{"query": "mutation { webhookSubscriptionCreate(topic: CUSTOMERS_CREATE, webhookSubscription: {callbackUrl: \\"https://yourapp.com/webhooks/customers-create\\", format: JSON}) { userErrors { field message } webhookSubscription { id } } }"}'

1curl -X POST 'https://mystore.myshopify.com/admin/api/2026-04/graphql.json' \
2  -H 'X-Shopify-Access-Token: shpat_your_token' \
3  -H 'Content-Type: application/json' \
4  -d '{"query": "{ customer(id: \\"gid://shopify/Customer/11223344\\") { id email displayName firstName tags numberOfOrders totalSpentV2 { amount currencyCode } emailMarketingConsent { marketingState } orders(first: 1, sortKey: CREATED_AT, reverse: true) { edges { node { id name totalPriceV2 { amount } } } } } }"}'

1# SendGrid dynamic template email
2curl -X POST 'https://api.sendgrid.com/v3/mail/send' \
3  -H 'Authorization: Bearer $SENDGRID_API_KEY' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "from": {"email": "hello@yourstore.com", "name": "Your Store"},
7    "personalizations": [{
8      "to": [{"email": "jane@example.com", "name": "Jane"}],
9      "dynamic_template_data": {
10        "first_name": "Jane",
11        "orders_count": 12,
12        "total_spent": "458.75"
13      }
14    }],
15    "template_id": "d-your-sendgrid-template-id"
16  }'

1# Query customers with marketing consent who haven't ordered in 90 days
2curl -X POST 'https://mystore.myshopify.com/admin/api/2026-04/graphql.json' \
3  -H 'X-Shopify-Access-Token: shpat_your_token' \
4  -H 'Content-Type: application/json' \
5  -d '{"query": "{ customers(first: 100, query: \\"email_marketing_consent_state:subscribed AND last_order_date:<2026-01-07\\") { edges { node { id email firstName numberOfOrders } } pageInfo { hasNextPage endCursor } } }"}'

Complete working code

This script handles the full welcome email flow: receives the `customers/create` webhook, validates the HMAC, fetches enriched customer data, checks marketing consent, and sends a personalized welcome email via SendGrid.

1import os, hmac, hashlib, base64, logging, requests
2from flask import Flask, request, abort
3
4logging.basicConfig(level=logging.INFO)
5app = Flask(__name__)
6
7SHOP_DOMAIN = os.environ['SHOPIFY_SHOP_DOMAIN']
8ACCESS_TOKEN = os.environ['SHOPIFY_ACCESS_TOKEN']
9APP_SECRET = os.environ['SHOPIFY_APP_SECRET']
10SENDGRID_KEY = os.environ['SENDGRID_API_KEY']
11TEMPLATE_ID = os.environ['SENDGRID_WELCOME_TEMPLATE_ID']
12
13SHOPIFY_URL = f'https://{SHOP_DOMAIN}/admin/api/2026-04/graphql.json'
14SHOPIFY_HEADERS = {'X-Shopify-Access-Token': ACCESS_TOKEN, 'Content-Type': 'application/json'}
15
16def gql(query):
17    resp = requests.post(SHOPIFY_URL, json={'query': query}, headers=SHOPIFY_HEADERS)
18    resp.raise_for_status()
19    return resp.json()
20
21def get_customer(customer_id):
22    q = f'{{ customer(id: "gid://shopify/Customer/{customer_id}") {{ id email firstName numberOfOrders totalSpentV2 {{ amount currencyCode }} emailMarketingConsent {{ marketingState }} }} }}'
23    return gql(q)['data']['customer']
24
25def send_email(customer):
26    payload = {
27        'from': {'email': 'hello@yourstore.com'},
28        'personalizations': [{
29            'to': [{'email': customer['email'], 'name': customer.get('firstName', '')}],
30            'dynamic_template_data': {
31                'first_name': customer.get('firstName', 'there'),
32                'total_spent': customer.get('totalSpentV2', {}).get('amount', '0')
33            }
34        }],
35        'template_id': TEMPLATE_ID
36    }
37    resp = requests.post('https://api.sendgrid.com/v3/mail/send', json=payload, headers={'Authorization': f'Bearer {SENDGRID_KEY}'})
38    return resp.status_code == 202
39
40@app.route('/webhooks/customers-create', methods=['POST'])
41def customer_created():
42    hmac_header = request.headers.get('X-Shopify-Hmac-Sha256', '')
43    computed = base64.b64encode(hmac.new(APP_SECRET.encode(), request.get_data(), hashlib.sha256).digest()).decode()
44    if not hmac.compare_digest(computed, hmac_header):
45        abort(401)
46    
47    data = request.get_json()
48    customer_id = data['id']
49    customer = get_customer(customer_id)
50    
51    if not customer or not customer.get('email'):
52        return '', 200
53    
54    # Always send transactional welcome (no consent check needed)
55    success = send_email(customer)
56    logging.info(f'Welcome email for {customer_id}: {"sent" if success else "failed"}')
57    return '', 200
58
59if __name__ == '__main__':
60    app.run(port=3000)

Error handling

Rate Limits for Shopify Customer API

1import time
2
3def gql_paginate_customers(url, headers, filter_query, max_retries=3):
4    cursor, customers = None, []
5    while True:
6        after = f', after: "{cursor}"' if cursor else ''
7        q = f'{{ customers(first: 100{after}, query: "{filter_query}") {{ edges {{ node {{ id email firstName }} }} pageInfo {{ hasNextPage endCursor }} }} }}'
8        for attempt in range(max_retries):
9            resp = requests.post(url, json={'query': q}, headers=headers)
10            if resp.status_code == 429:
11                time.sleep(2 ** attempt)
12                continue
13            break
14        data = resp.json()['data']['customers']
15        customers.extend(e['node'] for e in data['edges'])
16        available = resp.json().get('extensions', {}).get('cost', {}).get('throttleStatus', {}).get('currentlyAvailable', 1000)
17        if available < 100:
18            time.sleep(2)
19        if not data['pageInfo']['hasNextPage']:
20            break
21        cursor = data['pageInfo']['endCursor']
22    return customers

• Request only the customer fields you need — each additional connection (orders, addresses) adds query cost.
• Cache customer segments for scheduled campaigns — don't re-query Shopify for each individual send.
• Use the `query` parameter to filter customers server-side rather than fetching all and filtering client-side.
• Add 100ms delays between ESP sends when batch-processing large segments to avoid triggering spam filters.
• Monitor both Shopify GraphQL quota and ESP daily send limits — either can bottleneck large campaigns.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Shopify does not send emails via API — always use an external ESP (SendGrid, Resend, Mailchimp) for delivery.
• Distinguish transactional emails (welcome, order confirmation) from marketing emails — only marketing emails require explicit opt-in consent.
• Check emailMarketingConsent.marketingState === 'SUBSCRIBED' before sending any promotional email.
• Use the `query` filter parameter when fetching customers for campaigns — avoid pulling all customers and filtering client-side.
• Build an unsubscribe handler that calls `customerEmailMarketingConsentUpdate` to sync opt-outs back to Shopify.
• For Shopify Email's built-in 10,000 free monthly emails, use it for simple transactional sends; switch to an ESP when you need custom logic.
• Test email templates with Shopify's native preview feature before automating sends at scale.
• Always include an unsubscribe link in marketing emails — CAN-SPAM and GDPR compliance requirement.

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue