# Fix agent hitting SendGrid API rate limit mid welcome email blast

## TL;DR
The agent hits SendGrid's rate limit because it fires the whole blast as fast as possible. Throttle sends to a sustainable rate, honor 429s with backoff, and checkpoint progress. The blast is a paced job, not a race.

## The error
```text
Agent failed
SendGrid API rate limit hit mid welcome email blast. 500 emails unsent.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=agent hit sendgrid api rate limit mid welcome email blast run failed"
```

## Fix it

### Step 1: Checkpoint sent progress

```bash
Record which recipients already got the email.
```

Expected: A resume skips sent recipients.

### Step 2: Throttle the send rate

```bash
Add a rate limiter to the send loop at a sustainable pace.
```

Expected: Sends stay under the limit.

### Step 3: Honor 429 with backoff

```bash
On 429, wait and retry with backoff instead of failing.
```

Expected: Transient limits clear without losing progress.

### Step 4: Resume the blast

```bash
Restart from the checkpoint with throttling in place.
```

Expected: All recipients get exactly one email.

### Step 5: Monitor send metrics

```bash
Watch send rate and 429 counts during the blast.
```

Expected: The blast completes with zero 429s.

## When this applies

- Email blasts hit SendGrid rate limits
- Bulk welcome sends die partway
- You are building bulk email agents

## When it doesn't

- Every send fails (check the API key)
- Sends succeed but bounce (check the sender reputation)
- The limit hits on single sends (check the account plan)

## Compatibility

SendGrid mail send API rate limits. Any bulk-send agent.

## Variant phrasings

### sendgrid rate limit email blast agent

Same failure. Throttling plus checkpoints is the fix.

### agent 429 sendgrid welcome emails

429s mid-blast need backoff and resume, not a restart from zero.

### bulk email throttled sendgrid

Throttling is normal at scale. Build it in from the start.

## Why it happens

SendGrid rate-limits the mail send API, and a blast loop with no pacing hits the ceiling fast. Without checkpoints, the retry starts over and users get duplicates; without throttling, it hits the ceiling again. The job needs pacing and resume, not speed.

## Edge cases

- Dedicated IPs have their own warm-up limits; pace new IPs gently
- 429s during a blast can cascade into timeouts; keep the loop resilient
- Log per-recipient outcomes so partial blasts are reconcilable

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_oW9GVcYelvlbwpKkkLw2YQ