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

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

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:

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

Quick Migration Steps

Configure IP Pool

Create an IP Pool in SendPost with the same name as your SendGrid IP Pool, configured to route to SendGrid

Change the base URL

From: https://api.sendgrid.com
To: https://api.sendpost.io/v1/sendgrid

Update the API key header

From: Authorization: Bearer SG.xxxx
To: X-SubAccount-ApiKey: YOUR_SENDPOST_API_KEY

Send emails

Use the same payload format as before (including ip_pool_name)

Migration Example

Before (SendGrid)
After (SendPost)

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"
  }'

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"
  }'

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.

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

The following SendGrid features are not supported and will return an error if present:

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:

{
  "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 for tracking email status
View analytics for your SendGrid emails
Troubleshoot issues with the compatible API

Documentation

Guides

SDK Quickstarts

Common Use Cases

IP Pool Requirement

Quick Migration Steps

Migration Example

Supported SendGrid Features

Unsupported SendGrid Features

Response Mapping

Next Steps

​IP Pool Requirement

​Quick Migration Steps

​Migration Example

​Supported SendGrid Features

​Unsupported SendGrid Features

​Response Mapping

​Next Steps

IP Pool Requirement

Quick Migration Steps

Migration Example

Supported SendGrid Features

Unsupported SendGrid Features

Response Mapping

Next Steps