> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SendGrid-Compatible API

> Migrate from SendGrid with minimal code changes using SendPost's SendGrid-Compatible API.

If you're currently using SendGrid and want to migrate to SendPost, we offer a **SendGrid-Compatible API** that minimizes code changes.

***

## IP Pool Requirement

<Warning>
  **Mandatory Requirement**: To use the SendGrid-Compatible API, you must have an IP Pool configured in both SendGrid and SendPost with **the same name**.
</Warning>

The IP Pool name in your SendGrid requests (`ip_pool_name`) must match an IP Pool in SendPost that is configured to route traffic to your SendGrid provider. This ensures proper routing of emails through SendGrid.

**Setup Steps**:

1. Note the IP Pool name you use in SendGrid (e.g., "transactional" or "marketing")
2. Create an IP Pool in SendPost with **the exact same name**
3. Configure the SendPost IP Pool to route traffic to your SendGrid provider

***

## Quick Migration Steps

<Steps>
  <Step title="Configure IP Pool">
    Create an IP Pool in SendPost with the same name as your SendGrid IP Pool, configured to route to SendGrid
  </Step>

  <Step title="Change the base URL">
    * From: `https://api.sendgrid.com`
    * To: `https://api.sendpost.io/v1/sendgrid`
  </Step>

  <Step title="Update the API key header">
    * From: `Authorization: Bearer SG.xxxx`
    * To: `X-SubAccount-ApiKey: YOUR_SENDPOST_API_KEY`
  </Step>

  <Step title="Send emails">
    Use the same payload format as before (including `ip_pool_name`)
  </Step>
</Steps>

***

## Migration Example

<Tabs>
  <Tab title="Before (SendGrid)">
    ```bash theme={null}
    curl -X POST "https://api.sendgrid.com/v3/mail/send" \
      -H "Authorization: Bearer SG.xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "personalizations": [{
          "to": [{"email": "john@example.com", "name": "John"}]
        }],
        "from": {"email": "sender@example.com"},
        "subject": "Hello World",
        "content": [
          {"type": "text/plain", "value": "Hello!"},
          {"type": "text/html", "value": "<p>Hello!</p>"}
        ],
        "ip_pool_name": "transactional"
      }'
    ```
  </Tab>

  <Tab title="After (SendPost)">
    ```bash theme={null}
    curl -X POST "https://api.sendpost.io/v1/sendgrid/v3/mail/send" \
      -H "X-SubAccount-ApiKey: YOUR_SENDPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "personalizations": [{
          "to": [{"email": "john@example.com", "name": "John"}]
        }],
        "from": {"email": "sender@example.com"},
        "subject": "Hello World",
        "content": [
          {"type": "text/plain", "value": "Hello!"},
          {"type": "text/html", "value": "<p>Hello!</p>"}
        ],
        "ip_pool_name": "transactional"
      }'
    ```
  </Tab>
</Tabs>

<Note>
  The `ip_pool_name` in your request must match an IP Pool configured in SendPost that routes to SendGrid. Without this, the SendGrid-Compatible API will not know where to route your emails.
</Note>

***

## Supported SendGrid Features

| Feature                   | Supported | Notes                                                                            |
| ------------------------- | --------- | -------------------------------------------------------------------------------- |
| `from` / `to` / `subject` | ✅         | Direct mapping                                                                   |
| `content` (text/html)     | ✅         | Supports both plain text and HTML                                                |
| `reply_to`                | ✅         | Single reply-to address                                                          |
| `headers`                 | ✅         | Custom headers preserved                                                         |
| `custom_args`             | ✅         | Merged into headers                                                              |
| `categories`              | ✅         | Mapped to SendPost groups                                                        |
| `ip_pool_name`            | ✅         | **Required** - Must match an IP Pool in SendPost configured for SendGrid routing |
| `attachments`             | ✅         | Base64 encoded attachments                                                       |
| `personalizations`        | ✅         | Multiple recipients with personalization                                         |
| `substitutions`           | ✅         | Mapped to custom fields                                                          |
| Open tracking             | ✅         | `tracking_settings.open_tracking`                                                |
| Click tracking            | ✅         | `tracking_settings.click_tracking`                                               |

***

## Unsupported SendGrid Features

<Warning>
  The following SendGrid features are **not supported** and will return an error if present:
</Warning>

| Feature                       | Alternative                                                    |
| ----------------------------- | -------------------------------------------------------------- |
| `template_id`                 | Use SendPost's native template API or include content directly |
| `reply_to_list`               | Use single `reply_to` address                                  |
| `send_at` (scheduled sending) | Not available through this endpoint                            |
| `batch_id`                    | Not supported                                                  |
| `asm` (suppression groups)    | Use SendPost's `{{unsubscribe}}` template variable             |
| `mail_settings`               | Not supported                                                  |
| `subscription_tracking`       | Use SendPost's `{{unsubscribe}}` template variable             |
| `ganalytics`                  | Not supported                                                  |
| `attachments.disposition`     | All attachments treated as standard                            |
| `attachments.content_id`      | Inline images via CID not supported                            |

**Error Response for Unsupported Fields**:

```json theme={null}
{
  "errors": [{
    "message": "Field 'template_id' is not supported. Please use SendPost's native template API or include content directly.",
    "field": "template_id"
  }]
}
```

***

## Response Mapping

| SendGrid Response          | SendPost Behavior                               |
| -------------------------- | ----------------------------------------------- |
| HTTP 202 Accepted          | SendPost returns 202 with empty body on success |
| HTTP 400 Bad Request       | Validation errors in SendGrid format            |
| HTTP 401 Unauthorized      | Invalid or missing API key                      |
| HTTP 413 Payload Too Large | Request exceeds 30MB limit                      |

***

## Next Steps

* [Understand event types](/guides/sendgrid/event-types) for tracking email status
* [View analytics](/guides/sendgrid/analytics) for your SendGrid emails
* [Troubleshoot issues](/guides/sendgrid/troubleshooting) with the compatible API