> ## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.