> ## Documentation Index > Fetch the complete documentation index at: https://docs.autosend.com/llms.txt > Use this file to discover all available pages before exploring further. # Migrate from SendGrid to AutoSend > Use the SendGrid Migration API to move dynamic templates, contacts, lists, custom fields, and unsubscribe groups from SendGrid into AutoSend. export const AUTOSEND_PATHS = { dashboard: 'https://autosend.com/dashboard', apiKey: 'https://autosend.com/account/api-key', faqs: 'https://autosend.com/faq', marketingEmails: 'https://autosend.com/marketing-emails', webhooks: 'https://autosend.com/webhooks', composeByAutoSend: 'https://autosend.com/compose', emailActivity: 'https://autosend.com/email-activities', team: 'https://autosend.com/settings/team', pricing: 'https://autosend.com/pricing', verifyEmail: 'https://autosend.com/compose/email-builder?template=verify-email', welcomeEmail: 'https://autosend.com/compose/email-builder?template=welcome-email', productUpdate: 'https://autosend.com/compose/email-builder?template=product-update', newsletter: 'https://autosend.com/compose/email-builder?template=newsletter', automations: 'https://autosend.com/automations', globalSuppressions: 'https://autosend.com/suppressions/global', signup: 'https://autosend.com/signup', domains: 'https://autosend.com/settings/domains', smtpKey: 'https://autosend.com/settings/smtp', logoKit: 'https://asend.email/logo', contactsPage: 'https://autosend.com/contacts/list-and-segments', accountBilling: 'https://autosend.com/account/billing', accountUsage: 'https://autosend.com/account/usage', terms: 'https://autosend.com/legal/terms', inbound: 'https://autosend.com/email-activities/inbound' }; export const APP_PATHS = { home: '/', quickstart: '/quickstart', domainConfiguration: '/domain', apiReference: '/api-reference', sendEmail: '/api-reference/mails/send', bulkSendEmail: '/api-reference/mails/bulk', upsertContactApiRef: '/api-reference/contacts/upsert-contact', transactional: '/transactional-emails', emailActivity: '/transactional-emails/email-activity', emailTemplates: '/transactional-emails/email-templates', sendingEmail: '/quickstart/email-using-api', transactionalTroubleshooting: '/transactional-emails/troubleshooting', marketing: '/marketing-emails', campaigns: '/marketing-emails/campaigns', contacts: '/marketing-emails/contacts', contactsIntroduction: '/marketing-emails/contacts/introduction', contactsImportCsv: '/marketing-emails/contacts/import-csv', contactsLists: '/marketing-emails/contacts/lists', contactsSegments: '/marketing-emails/contacts/segments', contactsCustomFields: '/marketing-emails/contacts/contact-properties', contactsContactProperties: '/marketing-emails/contacts/contact-properties', createContactPropertyApiRef: '/api-reference/contact-properties/create', listContactPropertiesApiRef: '/api-reference/contact-properties/list', getContactPropertyApiRef: '/api-reference/contact-properties/get-by-name', deleteContactPropertyApiRef: '/api-reference/contact-properties/delete', sender: '/marketing-emails/sender', unsubscribeGroups: '/others/unsubscribe-groups', webhookIntroduction: '/others/webhooks/introduction', webhookEventType: '/others/webhooks/event-type', webhookRetries: '/others/webhooks/retries', webhookVerifyRequests: '/others/webhooks/verify-requests', dynamicTemplates: '/dynamic-templates', guides: '/guides', sitemap: '/sitemap.xml', team: '/others/team', automations: '/automations', events: '/automations/events', sendEventApi: '/api-reference/events/send-event', smtpIntroduction: '/quickstart/smtp', betterAuth: '/guides/better-auth', convexGuide: '/guides/convex', templateVariables: '/transactional-emails/variables', suppressions: '/others/suppressions', rateLimit: '/api-reference/rate-limit', nodejsSdk: '/sdk/nodejs', smtpIntegrationGuides: '/guides/smtp', apiKeys: '/api-keys', encryptedPayloads: '/others/encrypted-payloads', apiReferenceIntroduction: '/api-reference/introduction', lovableGuide: '/ai/integrations/lovable', aiIntroduction: '/ai/introduction', aiSkills: '/ai/skills', aiMcpServer: '/ai/mcp-server', aiLovable: '/ai/integrations/lovable', aiBolt: '/ai/integrations/bolt', aiV0: '/ai/integrations/v0', aiReplit: '/ai/integrations/replit', mcpClaude: '/ai/mcp-clients/claude', mcpCursor: '/ai/mcp-clients/cursor', mcpCopilot: '/ai/mcp-clients/copilot', mcpWindsurf: '/ai/mcp-clients/windsurf', mcpCodex: '/ai/mcp-clients/codex', mcpAntigravity: '/ai/mcp-clients/antigravity', mcpChatgpt: '/ai/mcp-clients/chatgpt', mcpRaycast: '/ai/mcp-clients/raycast', domainWarmup: '/marketing-emails/domain-warmup', projects: '/projects', createAutomationApi: '/api-reference/automations/create-automation', migrationSendgrid: '/migration/sendgrid', migrationResend: '/migration/resend', auth0CustomAction: '/guides/auth0-custom-action', accountBilling: '/others/account/billing', accountUsage: '/others/account/usage', inboundIntroduction: '/inbound/introduction', listInboundMessagesApi: '/api-reference/inbound-emails/list-messages', getInboundMessageApi: '/api-reference/inbound-emails/get-message', downloadInboundAttachmentApi: '/api-reference/inbound-emails/download-attachment', replyToInboundMessageApi: '/api-reference/inbound-emails/reply-to-message', wikiDailySendingLimit: '/wiki/daily-sending-limit' }; ## Overview AutoSend provides a set of public API endpoints to migrate your SendGrid assets into your AutoSend project: * Dynamic templates * Contacts and contact lists * Custom fields * Unsubscribe groups and their suppressed emails All endpoints are authenticated with your **AutoSend project API key** sent as a Bearer token. The SendGrid API key required to read from your SendGrid account is passed in the request body for each call. It is never persisted in plaintext. ## Prerequisites Before you start, make sure you have: 1. An **AutoSend project API key** - create one on the **API Keys** page. Keys look like `AS_xxxxxxxx_xxxxxxxxxxxxxxxxxxxx`. 2. A **SendGrid API key** - generate one in SendGrid under *Settings → API Keys*. The key should have at least these scopes: * `template_engine.read` - fetch templates * `marketing.read` - fetch contacts, lists, and custom field definitions * `suppressions.read` - fetch unsubscribe groups and suppressed emails 3. The base URL for all requests: `https://api.autosend.com/v1` ### Authentication Every request uses two headers: | Header | Value | | --------------- | -------------------------------- | | `Authorization` | `Bearer ` | | `Content-Type` | `application/json` | ## Recommended Flow Call `POST /migrations/sendgrid/plan` to confirm the SendGrid key is valid and see what will be migrated. Call `POST /migrations/sendgrid/migrate` with `migrateAll: true` or with specific IDs you want to import. Use `POST /migrations/sendgrid/sg-template` to migrate selected templates, or `POST /migrations/sendgrid/sg-unsubscribe-group` to migrate a single unsubscribe group. ## Endpoints ### Get migration plan Fetches a preview of everything that can be migrated from your SendGrid account: templates, unsubscribe groups, custom fields, contact lists, and the total contact count. **`POST /v1/migrations/sendgrid/plan`** #### Request body | Field | Type | Required | Description | | ---------------- | ------ | -------- | --------------------- | | `sendgridApiKey` | string | yes | Your SendGrid API key | ```bash cURL theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/plan \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key" }' ``` ```javascript NodeJS theme={null} const res = await fetch("https://api.autosend.com/v1/migrations/sendgrid/plan", { method: "POST", headers: { Authorization: `Bearer ${process.env.AUTOSEND_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ sendgridApiKey: process.env.SENDGRID_API_KEY, }), }); const data = await res.json(); ``` ```python Python theme={null} import os import requests res = requests.post( "https://api.autosend.com/v1/migrations/sendgrid/plan", headers={ "Authorization": f"Bearer {os.environ['AUTOSEND_API_KEY']}", "Content-Type": "application/json", }, json={"sendgridApiKey": os.environ["SENDGRID_API_KEY"]}, ) data = res.json() ``` #### Response `200` ```json expandable theme={null} { "success": true, "message": "Migration plan fetched successfully", "data": { "contactsCount": 12453, "templatesCount": 24, "templates": [ { "templateId": "d-abc123", "templateName": "Welcome email", "subject": "Welcome to Acme", "htmlContent": "...", "thumbnailUrl": "https://...", "updatedAt": "2025-08-12T10:24:11Z" } ], "unsubscribeGroups": [ { "groupId": "12345", "name": "Product updates", "description": "Monthly product newsletter", "isActive": true, "unsubscribeCount": 42 } ], "customFields": [ { "sendgridFieldId": "e1_T", "sendgridFieldName": "company", "autosendFieldName": "company", "fieldType": "string" } ], "reservedFields": [ { "sendgridFieldId": "_rf0_T", "sendgridFieldName": "first_name", "fieldType": "string" } ], "contactLists": [ { "id": "list-uuid-1", "name": "Newsletter subscribers", "contactCount": 8123 } ], "contactListsCount": 5 } } ``` ### Run the full migration Kicks off a background migration job that imports the selected SendGrid assets into your AutoSend project. Returns a `bulkOperationId` immediately; the work continues in the background. **`POST /v1/migrations/sendgrid/migrate`** #### Request body | Field | Type | Required | Default | Description | | ------------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | `sendgridApiKey` | string | yes | - | Your SendGrid API key | | `migrateAll` | boolean | no | `false` | If `true`, migrate everything returned by `/plan`. Per-type ID arrays below are populated from the plan when empty. | | `templateIds` | string\[] | no | `[]` | Specific SendGrid template IDs to migrate | | `unsubscribeGroupIds` | string\[] | no | `[]` | Specific SendGrid unsubscribe group IDs | | `contactListIds` | string\[] | no | `[]` | Specific SendGrid contact list IDs | | `customFieldMappings` | object\[] | no | `[]` | SendGrid to AutoSend custom field mappings (see schema below) | | `ignoreTemplates` | boolean | no | `false` | Skip templates phase | | `ignoreUnsubscribeGroups` | boolean | no | `false` | Skip unsubscribe groups phase | | `ignoreContactLists` | boolean | no | `false` | Skip contact lists phase | | `ignoreCustomFields` | boolean | no | `false` | Skip custom fields phase | | `ignoreContacts` | boolean | no | `false` | Skip contacts phase | `customFieldMappings` item schema: ```json theme={null} { "sendgridFieldId": "e1_T", "sendgridFieldName": "company", "autosendFieldName": "company", "fieldType": "string" } ``` `fieldType` must be one of: `string`, `number`, `date`. #### Migration phases The job runs in this order: 1. **Custom fields** - creates AutoSend custom field definitions from the mappings. 2. **Templates** - fetches each SendGrid template's active version. Images hosted on `cdn.mcauto-images-production.sendgrid.net` are downloaded and re-uploaded to your AutoSend media library, and the HTML is rewritten to point at the new URLs. 3. **Unsubscribe groups** - creates the matching suppression group in AutoSend and imports its suppressed email list. 4. **Contact lists** - creates the AutoSend list metadata. 5. **Contacts** - uses SendGrid's Export Contacts API to import all global contacts, then associates them with the lists created in step 4. #### Example A - migrate everything ```bash cURL theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/migrate \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key", "migrateAll": true }' ``` ```javascript NodeJS theme={null} const res = await fetch("https://api.autosend.com/v1/migrations/sendgrid/migrate", { method: "POST", headers: { Authorization: `Bearer ${process.env.AUTOSEND_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ sendgridApiKey: process.env.SENDGRID_API_KEY, migrateAll: true, }), }); const { data } = await res.json(); console.log(data.bulkOperationId); ``` ```python Python theme={null} import os import requests res = requests.post( "https://api.autosend.com/v1/migrations/sendgrid/migrate", headers={ "Authorization": f"Bearer {os.environ['AUTOSEND_API_KEY']}", "Content-Type": "application/json", }, json={ "sendgridApiKey": os.environ["SENDGRID_API_KEY"], "migrateAll": True, }, ) print(res.json()["data"]["bulkOperationId"]) ``` #### Example B - migrate selected assets only ```bash theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/migrate \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key", "templateIds": ["d-abc123", "d-def456"], "contactListIds": ["list-uuid-1"], "customFieldMappings": [ { "sendgridFieldId": "e1_T", "sendgridFieldName": "company", "autosendFieldName": "company", "fieldType": "string" } ], "ignoreUnsubscribeGroups": true }' ``` #### Example C - contacts only, skip everything else ```bash theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/migrate \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key", "migrateAll": true, "ignoreTemplates": true, "ignoreUnsubscribeGroups": true, "ignoreCustomFields": true }' ``` #### Response `202 Accepted` ```json theme={null} { "success": true, "message": "SendGrid migration initiated successfully", "data": { "bulkOperationId": "65fa1d2b8c9a4f1234567890", "status": "PENDING", "message": "SendGrid migration initiated successfully" } } ``` Hold on to the `bulkOperationId`. Your AutoSend dashboard shows progress against it. #### Common errors | HTTP | Code | Meaning | | ---- | ------------------------------------ | ----------------------------------------------------------------------- | | 400 | `SENDGRID_MIGRATION_IN_PROGRESS` | A migration is already running for this project - wait for it to finish | | 400 | `SENDGRID_NO_ITEMS_TO_MIGRATE` | Nothing selected and `migrateAll` was not set | | 500 | `SENDGRID_FAILED_TO_FETCH_PLAN` | SendGrid API key is invalid or rejected | | 500 | `SENDGRID_MIGRATION_CREATION_FAILED` | Could not schedule the migration job - retry shortly | ### Migrate one or more templates Migrate specific SendGrid dynamic templates without touching anything else. Useful for one-off moves or for syncing a template after edits in SendGrid. Always test migrated templates that contain complex Handlebars expressions before sending production traffic to them. **`POST /v1/migrations/sendgrid/sg-template`** #### Request body | Field | Type | Required | Default | Description | | --------------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------- | | `sendgridApiKey` | string | yes | - | Your SendGrid API key | | `sendgridTemplateIds` | string\[] | yes | - | SendGrid dynamic template IDs (e.g. `d-abc123`) | | `onExistUpdateHTML` | boolean | no | `false` | If a template with the same ID already exists in AutoSend, overwrite its HTML and subject | ```bash cURL theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/sg-template \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key", "sendgridTemplateIds": ["d-abc123", "d-def456"], "onExistUpdateHTML": true }' ``` ```javascript NodeJS theme={null} const res = await fetch("https://api.autosend.com/v1/migrations/sendgrid/sg-template", { method: "POST", headers: { Authorization: `Bearer ${process.env.AUTOSEND_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ sendgridApiKey: process.env.SENDGRID_API_KEY, sendgridTemplateIds: ["d-abc123", "d-def456"], onExistUpdateHTML: true, }), }); ``` ```python Python theme={null} import os import requests res = requests.post( "https://api.autosend.com/v1/migrations/sendgrid/sg-template", headers={ "Authorization": f"Bearer {os.environ['AUTOSEND_API_KEY']}", "Content-Type": "application/json", }, json={ "sendgridApiKey": os.environ["SENDGRID_API_KEY"], "sendgridTemplateIds": ["d-abc123", "d-def456"], "onExistUpdateHTML": True, }, ) ``` #### Response `200` ```json theme={null} { "success": true, "message": "Template migrated successfully", "data": [ { "templateId": "d-abc123", "templateName": "Welcome email", "subject": "Welcome to Acme", "templateType": "TRANSACTIONAL", "createdAt": "2026-05-14T08:12:11.234Z" } ] } ``` Images referenced from `cdn.mcauto-images-production.sendgrid.net` are automatically downloaded and re-hosted on AutoSend so your templates continue to render after you turn SendGrid off. ### Migrate one unsubscribe group Migrate a single SendGrid unsubscribe group (ASM group), and optionally its suppressed email addresses. **`POST /v1/migrations/sendgrid/sg-unsubscribe-group`** #### Request body | Field | Type | Required | Default | Description | | ---------------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `sendgridApiKey` | string | yes | - | Your SendGrid API key | | `sendgridUnsubscribeGroupId` | string \| number | yes | - | The SendGrid unsubscribe group ID | | `addEmailsInSuppression` | boolean | no | `true` | Also import all currently suppressed email addresses for the group | | `groupExist` | boolean | no | `false` | If `true`, skip creating a new AutoSend suppression group and only import the emails into the existing group with the matching `groupId` | ```bash cURL theme={null} curl --request POST \ --url https://api.autosend.com/v1/migrations/sendgrid/sg-unsubscribe-group \ --header 'Authorization: Bearer AS_YOUR_AUTOSEND_KEY' \ --header 'Content-Type: application/json' \ --data '{ "sendgridApiKey": "SG.your_sendgrid_api_key", "sendgridUnsubscribeGroupId": 12345, "addEmailsInSuppression": true }' ``` ```javascript NodeJS theme={null} const res = await fetch( "https://api.autosend.com/v1/migrations/sendgrid/sg-unsubscribe-group", { method: "POST", headers: { Authorization: `Bearer ${process.env.AUTOSEND_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ sendgridApiKey: process.env.SENDGRID_API_KEY, sendgridUnsubscribeGroupId: 12345, addEmailsInSuppression: true, }), } ); ``` ```python Python theme={null} import os import requests res = requests.post( "https://api.autosend.com/v1/migrations/sendgrid/sg-unsubscribe-group", headers={ "Authorization": f"Bearer {os.environ['AUTOSEND_API_KEY']}", "Content-Type": "application/json", }, json={ "sendgridApiKey": os.environ["SENDGRID_API_KEY"], "sendgridUnsubscribeGroupId": 12345, "addEmailsInSuppression": True, }, ) ``` #### Response `200` When the group was newly created and emails were imported: ```json theme={null} { "success": true, "message": "Unsubscribe group migrated successfully", "data": { "groupId": "12345", "addedCount": 42, "entries": [ { "id": "65fa...", "email": "user@example.com", "groupId": "12345" } ] } } ``` If the group already existed and `addEmailsInSuppression` was `false`, the response is the suppression group DTO instead. ## FAQ The key is held in memory for the lifetime of the migration job and encrypted at rest while the background job is queued. Yes. Templates are upserted by their SendGrid `templateId` when `onExistUpdateHTML: true`. Contacts and suppressed emails are upserted by email address, so duplicates are safe. Custom fields are not deduplicated - re-running custom-field migration will fail the duplicate creations and report them in the metrics, but the run continues. Templates and unsubscribe groups are usually done in seconds. Contacts use SendGrid's Export Contacts API, which takes around 1 minute per 100k contacts on SendGrid's side, plus the time to import on our side. The request returns immediately - the job keeps running after your HTTP connection closes. SendGrid-hosted images (`cdn.mcauto-images-production.sendgrid.net`) are automatically downloaded and re-uploaded to AutoSend's media library, and the HTML is rewritten to point at the new URLs. `/plan` returns whatever the scopes allow. If a scope is missing (e.g. you didn't grant `suppressions.read`), that section comes back empty and the corresponding migration phase silently skips it. Grant the missing scope and re-run if needed. ## Support If a migration fails or produces unexpected results, send us: 1. The `bulkOperationId` returned by `/migrate` 2. Your AutoSend project ID 3. The approximate time of the request Email [support@autosend.com](mailto:support@autosend.com) with these details and we'll investigate. ## Next Steps Manage the templates you just migrated from SendGrid. Browse and segment the contacts imported from SendGrid. Review the suppression groups created during migration. Verify your sending domain so migrated templates can start sending.