SendGrid: Telltide Seed Address Guide

SendGrid Marketing Campaigns has a significant constraint for automation monitoring: contacts added to a list before an automation was set to "Live" do not receive the automation emails. Only contacts added after activation are eligible. This means seeds must be added to the automation's entry list after the automation goes live - not before. Plan your activation sequence accordingly.

Quick reference

---

1. Scheduled / one-off sends (Single Sends)

SendGrid Single Sends are one-off campaigns. The audience is defined by selecting contact lists and/or segments. Seeds must be in at least one targeted list or segment.

Where to add seed addresses

Add the seed contact to any contact list selected as a recipient in the Single Send. The simplest approach: maintain a "Telltide Seeds" contact list and include it in every Single Send's recipient selection.

The instructions below split into two paths. Use the Non-technical path if you work in CRM or Lifecycle and add contacts through the Marketing Campaigns UI. Use the Technical path if you are an email-developer or ops engineer enrolling seeds programmatically.

Non-technical path

For CRM and Lifecycle managers without dev access. No code required.

Option A: Add a seed contact manually via UI

1. Navigate to Marketing > Contacts > Add Contacts > Manual Add
2. Enter the seed email address
3. Fill in any additional fields: first name, last name, custom field values
4. Select the list(s) to add this contact to (or add to "All Contacts" and add to a list separately)
5. Click Add Contacts

Option B: Add a seed contact via CSV upload

1. Navigate to Marketing > Contacts > Add Contacts > Upload CSV
2. Select or create the target list
3. Upload your CSV file. The email column header must be exactly email (lowercase)
4. Map additional columns to SendGrid contact fields or custom fields
5. Click Add Contacts. Contacts are queued for upload (asynchronous processing)

Required CSV header: email

Optional headers: first_name, last_name, address_line_1, address_line_2, city, state_province_region, postal_code, country, phone_number, whatsapp, line, facebook, unique_name, plus any custom field column names you've defined.

Note: phone_number_id is a contact identifier (one of the four primary keys, alongside email, external_id, anonymous_id), not a normal optional profile field. Use phone_number for storing a phone value.

Option C: Capture the seed via a public sign-up form

If your team uses SendGrid sign-up forms to grow lists, you can submit the seed address through the same sign-up form that real subscribers use. Open the public form URL, enter the seed email, and complete any required fields. The seed lands in the form's target list automatically. This is useful when you want the seed to follow the exact same intake path as real customers (including any double opt-in confirmation step).

Technical path

For email-developer and ops engineers enrolling seeds programmatically through the v3 Marketing API.

Add a seed contact via API

PUT https://api.sendgrid.com/v3/marketing/contacts
Authorization: Bearer {{api_key}}
Content-Type: application/json

{
  "list_ids": ["{{list_id}}"],
  "contacts": [
    {
      "email": "seed@example.com",
      "first_name": "Seed",
      "last_name": "Monitor",
      "custom_fields": {
        "e1_T": "value_for_custom_text_field"
      }
    }
  ]
}

Or via curl:

curl -X PUT https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_ids": ["LIST_ID"],
    "contacts": [
      { "email": "seed@example.com", "first_name": "Seed", "last_name": "Monitor" }
    ]
  }'

This is an asynchronous upsert. The response is 202 Accepted with a body containing { "job_id": "..." }. The 202 means the contact is queued, not stored, so retry and idempotency logic should not treat it as a synchronous success. The contact is available after processing completes. Always poll the job_id until status is completed before assuming the seed appears in a Single Send's recipient count. Processing typically takes seconds but can take 15 minutes or more during peak load and occasionally hangs, so do not assume immediate availability. Check job status:

GET https://api.sendgrid.com/v3/marketing/contacts/imports/{job_id}

Custom field references in API: Custom field IDs use the format {field_id}_{field_type} (e.g., e1_T for a text field, e2_N for a number field). Retrieve field IDs from:

GET https://api.sendgrid.com/v3/marketing/field_definitions

Always-on flow coverage

Always-on or triggered flows in SendGrid are built as Automations. Unlike a Single Send, you cannot attach a recipient list to a single message inside an Automation, so the seed has to satisfy the Automation's entry condition before any of its emails will reach it. Pick the approach that matches the Automation's entry criterion:

• Entry criterion is "first time added to a list": Add the seed to that exact entry list (after the Automation is set to Live, see Section 2). Every contact added to the entry list, including the seed, is enrolled and walks through the full series. Maintaining one shared "Telltide Seeds" list will not work here unless the entry list is the seeds list itself; the seed must be a member of the configured entry list.
• Entry criterion is "first time added to a segment": Make the seed match the segment's filter criteria. Typically this means setting the seed's reserved fields or custom-field values so the segment query evaluates true, then waiting for the segment to refresh (1 hour for active segments, up to 24 hours for inactive). Segment-triggered Automations do not fire instantly; budget for the refresh delay when validating coverage. If you need predictable seed timing on an always-on flow, change the Automation to a list-based entry and use the bullet above.
• Single Send broadcasts via the UI (one-off, not always-on): No special configuration is needed. Just keep the seed in any audience list selected as a recipient in the Single Send.

To confirm coverage, query the Automation's entry list (or run the segment query) for the seed's contact_id before activating, and re-check after each refresh cycle if you are using a segment.

Profile attributes required

Seeds need:

• email (required)
• first_name, last_name if used in personalization
• Values for any custom fields referenced in email content

Ensuring seeds receive the same version as real recipients

Exclusions: Single Sends allow exclusion of up to 5 segments and 50 lists. Verify the seed is not in any excluded list or segment.

If a contact is on multiple targeted lists: They receive the email only once (deduplication is automatic).

Unsubscribe mechanism: Each Single Send is configured with one of: an unsubscribe group, a custom unsubscribe link, or the global unsubscribe link. If a group is used, check the seed's status in that group. If the global unsubscribe link is used, only GET /v3/asm/suppressions/global/{email} matters. If a custom link is used, check whatever suppression list the customer's link writes to. A seed that is globally unsubscribed will not receive the email regardless of which mechanism is configured.

Gotchas

Global unsubscribes override everything: A seed that is globally unsubscribed (opted out of all email) will not receive any Single Send regardless of list membership. A seed can also be silently suppressed by other categories. Check the full set:

• GET /v3/asm/suppressions/global/{email}, global unsubscribe
• GET /v3/suppression/bounces/{email}, bounces
• GET /v3/suppression/blocks/{email}, blocks
• GET /v3/suppression/invalid_emails/{email}, invalid
• GET /v3/suppression/spam_reports/{email}, spam reports
• GET /v3/asm/suppressions/{email}, all group unsubscribes for this email

Unsubscribe group conflicts with Subscription Tracking: Do not enable the "Subscription Tracking" setting (Settings > Tracking > Subscription Tracking) if you use Marketing Campaigns. These two systems conflict with each other.

---

2. Ongoing / automated journeys (Automations)

SendGrid Marketing Campaigns Automations are time-delayed email series triggered by a contact being added to a specific list or segment.

How Automations work

Each automation has:

• Entry criteria: One list (or segment) addition event - the "first time a contact is added to [list]"
• Email series: Multiple emails with configurable time delays between them
• Live state required: Contacts added before the automation was set to Live do not receive emails. Only additions after activation are eligible.

Critical workflow for seed monitoring

Never add seeds to the entry list before going Live. The correct sequence is:

1. Build the automation and set it to Live
2. After confirmation the automation is Live, add the seed contact to the entry list
3. The seed enters the automation and begins receiving the email series

Step-by-step: Set automation to Live and add seed

1. Navigate to Marketing > Automations and open the target automation
2. Open the Automation Options dropdown and select Set Live to activate it
3. Confirm the automation status shows "Live"
4. Navigate to Marketing > Contacts and add the seed contact to the automation's entry list (using any method from Section 1)
5. The seed begins receiving the automation emails according to the configured delay schedule

Automation trigger types and limitations

SendGrid Marketing Campaigns automations have one of two entry criteria:

Note: segment entry is evaluated only when the segment refreshes, which ranges from every 1 hour for active segments to every 24 hours for inactive segments. For reliable seed timing, prefer a list-based entry list.

SendGrid Automations do NOT natively support:

• Date-based triggers (birthday, anniversary)
• Behavioral triggers (abandoned cart, browse abandonment, purchase events)
• Custom event triggers

For birthday, cart abandonment, or post-purchase automation monitoring in SendGrid, you need either:

1. A third-party integration that manages these triggers externally and adds contacts to SendGrid lists at the right moment, OR
2. The SendGrid v3 Mail Send API (POST /v3/mail/send) for transactional sends - which is managed entirely outside the Marketing Campaigns automation builder

Profile requirements per journey type

Welcome automation (list-addition trigger):

• Seed: email address, added to entry list after automation is Live
• No additional attributes needed beyond personalization fields in the email

Date-based automations (birthday, anniversary):

• Not natively supported in SendGrid Automations
• Workaround: Build an external system that adds contacts to a "birthday trigger" list on the day of their birthday. The automation triggers when the contact is added to that list.
• Seed approach: Create a "Birthday Trigger" list. Add the seed to this list on the day you want to test. The automation fires.

Abandoned cart / post-purchase:

• Not natively supported in SendGrid Automations
• Use the transactional POST /v3/mail/send endpoint for these use cases:

POST https://api.sendgrid.com/v3/mail/send
Authorization: Bearer {{api_key}}
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{ "email": "seed@example.com" }],
      "dynamic_template_data": {
        "first_name": "Seed",
        "cart_total": "49.99",
        "product_name": "Widget Pro",
        "cart_url": "https://yourstore.com/cart"
      }
    }
  ],
  "from": { "email": "sender@yourdomain.com", "name": "Your Brand" },
  "template_id": "d-xxxxxxxxxxxx",
  "asm": {
    "group_id": 12345
  }
}

For transactional sends, seed monitoring is straightforward: include the seed address as a recipient in the API call.

---

Ensuring seeds progress through the full automation

Entry is once only (default): Contacts can only enter an automation once under the "first time added to list" trigger. To re-test the automation with the same seed:

1. Remove the seed from the entry list
2. Wait for the removal to process
3. Re-add the seed to the entry list

The automation treats the re-addition as a new entry event.

Alternatively: Create a duplicate test automation with a separate entry list. Add the seed to the test automation's list. This isolates testing from the production automation.

Mid-automation email edits: Edits to a Live automation only apply to contacts who enter after the edit. Contacts already mid-series continue receiving the previously generated content. To verify edited content with a seed, you must trigger a new entry (remove and re-add).

Unsubscribe group check at each email: If the seed unsubscribes from the unsubscribe group between email 1 and email 2, they will not receive email 2 or beyond.

---

How to reset seeds for repeated automation testing

Remove and re-add: Remove the seed from the entry list (DELETE /v3/marketing/lists/{list_id}/contacts), then re-add them. This creates a new entry event.

Use a different seed address per cycle: Create seed@example.com, seed2@example.com, etc. Each is a fresh contact with no automation history.

Remove the seed contact from the automation's processed list: SendGrid does not expose a direct API to clear a contact's automation history. The remove-and-re-add method is the supported approach.

---

3. Platform-specific considerations

API options

Create or update contacts (upsert):

PUT https://api.sendgrid.com/v3/marketing/contacts
Authorization: Bearer {{api_key}}

Asynchronous. Returns a job_id. Check status with GET /v3/marketing/contacts/imports/{job_id}.

Create a contact list:

POST https://api.sendgrid.com/v3/marketing/lists

Add contacts to a list:

PUT https://api.sendgrid.com/v3/marketing/contacts

(Include list_ids in the request body)

Remove contacts from a list:

DELETE https://api.sendgrid.com/v3/marketing/lists/{id}/contacts?contact_ids={ids}

contact_ids is a comma-separated list of contact UUIDs (not email addresses), for example ?contact_ids=id1,id2. Look up the contact_id first via POST /v3/marketing/contacts/search before calling this endpoint.

Search contacts:

POST https://api.sendgrid.com/v3/marketing/contacts/search
{
  "query": "email LIKE 'seed%'"
}

Transactional email send:

POST https://api.sendgrid.com/v3/mail/send

Synchronous, immediate send. Used for transactional emails outside the automation builder.

Check global unsubscribe:

GET https://api.sendgrid.com/v3/asm/suppressions/global/{email}

Remove from global unsubscribe:

DELETE https://api.sendgrid.com/v3/asm/suppressions/global/{email}

Get all custom field definitions:

GET https://api.sendgrid.com/v3/marketing/field_definitions

API key location: Settings > API Keys > Create API Key. For Marketing Campaigns, the key needs "Marketing" permission scope.

Rate limits

SendGrid rate limits are per-endpoint, not global. Most v3 endpoints return 429 with a Retry-After header when exceeded. /v3/mail/send does not enforce a per-second rate limit but is bound by your plan's daily and monthly volume. Some Marketing Campaigns endpoints (for example, segment refresh) have very tight per-day limits, so consult the official rate-limits page before bulk operations. Monitor X-RateLimit-Limit and X-RateLimit-Remaining headers where they are returned.

PUT /v3/marketing/contacts accepts batches up to 30,000 contacts or 6 MB per request.

Duplicate contact handling

Email address is the unique identifier. Sending PUT /v3/marketing/contacts with an existing email updates the contact's data rather than creating a duplicate. A contact can be on multiple lists simultaneously - they are counted once for billing regardless of how many lists they appear on.

Platform-specific terminology

Known limitations and workarounds

No native date-based, cart abandonment, or behavioral triggers. SendGrid Marketing Campaigns Automations only trigger on list/segment addition. Use external systems to add contacts to trigger lists at the right moment, or use the transactional POST /v3/mail/send API for these email types.

Contacts added before automation goes Live are not eligible. This is the most important constraint for seed timing. Always activate the automation before adding seeds.

The contacts upload is asynchronous. After calling PUT /v3/marketing/contacts, the contact is not immediately available or included in sends. Processing typically takes seconds but can take longer during peak load. Check job status before assuming the contact is ready.

Removing a contact from a list and re-adding re-triggers the automation. This is both the limitation (accidental re-trigger) and the workaround (intentional reset for re-testing).

Subscription Tracking conflicts with Marketing Campaigns. If "Subscription Tracking" is enabled (Settings > Tracking > Subscription Tracking), it interferes with the unsubscribe mechanism in Marketing Campaigns. Disable it if you're using the Marketing Campaigns product.

Custom field IDs are not human-readable. Custom fields are referenced in the API by internal IDs (e.g., e1_T). Retrieve these from GET /v3/marketing/field_definitions before building seed management scripts.