How to Migrate from Sendgrid’s Mail Send API to Netcore Email API

As mentioned earlier it’s super easy to migrate from Sendgrid’s Mail Send API to Netcore Email API without any re-work. Just, change the API endpoint and key in your existing Sendgrid’s API code or in the SDK/code library with that of Netcore Email API and you’re done.

Neetcore Email API Migration API endpoint: https://sgapi.netcorecloud.net/

While most of the important parameters are already covered in the scope of this migration API, but there are still a few which Netcore Email API doesn’t support.

Here’s an extensive list of Sendgrid’s APIs and it’s parameter which Netcore Email API supports:

Type: Email Send

Method: POST

Endpoint: /v3/mail/send

# List of Sendgrid parameters Supported in Netcore Email API
Migration API or not?
Description
Personalization
An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled.
1
personalization.to.email Yes Email address of the person to whom you are sending an email.
2
personalization.to.name Yes The name of the person to whom you are sending an email.
3
personalization.cc.email Yes Email address of the recipient who will receive a copy of your email.
4
personalization.cc.name No Name of the recipient who will receive a copy of your email.
5
personalization.bcc.email No The email address of the person to whom you are sending an email in bcc.
6
personalization.bcc.name No The name of the person to whom you are sending an email in bcc.
7
personalization.subject Yes The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310
8
personalization.headers No A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC
9
personalization.substitutions Yes A collection of key/value pairs following the pattern "substitution_tag":"value to substitute". The key/value pairs must be strings. These substitutions will apply to the text and HTML content of the body of your email, in addition to the subject and reply-to parameters.
10
personalization.custom_args Yes Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used.
13
personalization.send_at No A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden.
14
from    
15
from.email Yes The email address of the person to whom you are sending an email.
16
from.name Yes The name of the person to whom you are sending an email.
17
reply_to    
18
reply_to.email Yes The email address of the person to whom recipients are going to send replies to.
19
reply_to.name No The name of the person to whom recipients are going to send replies to.
20
subject Yes The subject of your email.
content
An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the type and value parameters.
22
content.type No The mime type of the content you are including in your email. For example, “text/plain” or “text/html”.
23
content.value Yes The actual content of the specified mime type that you are including in your email.
Attachments
An array of objects in which you can specify any attachments you want to include.
25
attachments.content Yes The Base64 encoded content of the attachment.
26
attachments.type No The mime type of the content you are attaching. For example, “text/plain” or “text/html”.
27
attachments.filename Yes The filename of the attachment.
28
attachments.disposition No The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file).
29
attachments.content_id No The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email.
30
template_id Yes The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level.
31
sections No An object of key/value pairs that define block sections of code to be used as substitutions. The key/value pairs must be strings.
32
headers No An object containing key/value pairs of header names and the value to substitute for them. The Key/value pairs must be strings. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers.
33
categories Yes An array of category names for this message. Each category name may not exceed 255 characters.
34
custom_args Yes Values that are specific to the entire send that will be carried along with the email and its activity data. Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes.
35
send_at No A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. You can't schedule more than 72 hours in advance. If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.
36
batch_id No This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html
asm
An object allowing you to specify how to handle unsubscribes.
38
asm.group_id No The unsubscribe group to associate with this email.
39
asm.groups_to_display No An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.
40
ip_pool_name No The IP Pool that you would like to send this email from.
mail_settings
A collection of different mail settings that you can use to specify how you would like this email to be handled.
42
mail_settings.bcc.enable No This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent. Indicates if this setting is enabled.
43
mail_settings.bcc.email Yes The email address that you would like to receive the BCC.
44
mail_settings.bypass_list_management.enable No Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email.
45
mail_settings.footer.enable Yes Indicates if this setting is enabled.
46
mail_settings.footer.text No The plain text content of your footer.
47
mail_settings.footer.html No The HTML content of your footer.
48
mail_settings.sandbox_mode.enable No This allows you to send a test email to ensure that your request body is valid and formatted correctly.

Indicates if this setting is enabled.
49
mail_settings.spam_check.enable No This allows you to test the content of your email for spam.

Indicates if this setting is enabled.
50
mail_settings.spam_check.threshold No The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.
51
mail_settings.spam_check.post_to_url No An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to.
Tracking_settings
Settings to determine how you would like to track the metrics of how your recipients interact with your email.
53
tracking_settings.click_tracking.enable Yes Allows you to track whether a recipient clicked a link in your email.

Indicates if this setting is enabled.
54
tracking_settings.click_tracking.enable_text No Indicates if this setting should be included in the text/plain portion of your email.
55
tracking_settings.open_tracking.enable Yes Allows you to track whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.Indicates if this setting is enabled.
56
tracking_settings.open_tracking.substitution_tag No Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel.
57
tracking_settings.subscription_tracking.enable No Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.
Indicates if this setting is enabled.
58
tracking_settings.subscription_tracking.html No Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>
59
tracking_settings.subscription_tracking.text No HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>
60
tracking_settings.subscription_tracking.substitution_tag No A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the text and html parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.
61
tracking_settings.ganalytics.enable No Allows you to enable tracking provided by Google Analytics. Indicates if this setting is enabled.
62
tracking_settings.ganalytics.utm_source No Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)
63
tracking_settings.ganalytics.utm_medium No Name of the marketing medium. (e.g. Email)
64
tracking_settings.ganalytics.utm_content No Used to identify any paid keywords.
65
tracking_settings.ganalytics.utm_term No Used to differentiate your campaign from advertisements.
66
tracking_settings.ganalytics.utm_campaign No The name of the campaign.

What will happen if a unsupported parameter is passed to Netcore Email API?

Netcore Email API will simply ignore the parameter and its payload in case it is not in the supported list of parameters.

In case you are already using some parameter with Sendgrid which is currently unsupported with Netcore Email API, then please contact our Technical Support team on [email protected]

How to use Netcore Email API migration APIs?

Here is the step by guide to help you migrate from Sendgrid to Netcore Email API using our migration API:

Step 1: Create Netcore Email API Account: That’s the first step, just go and Signup for a free trial at Netcore Email API.

Step 2: Configure your sender domain: If you want to use your own sending domain to test emails, then that domain needs to be first configured and get activated on your Netcore Email API account. Once you have added the domain, done with the DNS settings, then the domain or you can simply test the email sending using one of our sandbox domain. Navigate to Settings → Sandbox to get the sandbox sending domain to send emails.

Step 3: Get your API key: Once you have the domain ready, navigate to Settings → Integration → API to get your Netcore Email API’s API key.

Step 4: Change the Sendgrid’s API endpoint and API key: Open your code library which is currently been used to send emails. Change the Sendgrid’s API Key with that of Netcore Email API’s key. Also, change the Sendgrid’s API endpoint mentioned in your code with that of Netcore Email API.

Sendgrid’s endpoint: https://api.sendgrid.com/v3/ to be changed with Netcore Email API’s migration API endpoint: https://sgapi.netcorecloud.net/v3/

Step 5: Deploy and send a test email: Now, you’re ready to send your first test email.

Your Sendgrid API call might look like the following:

curl --request POST \
--url https://api.sendgrid.com/v3/mail/send \
--header 'authorization: Bearer <YOUR SENDGRID API KEY>' \
--header 'content-type: application/json' \
--data '{"personalizations":[{"to":[{"email":"<RECIPIENT EMAIL ID>","name":"<RECIPIENT NAME>"}],"subject":"This is a test mail"}],"content": [{"type": "text/plain", "value": "Hello, How are you?"}],"from":{"email":"<FROM EMAIL ID>","name":"<FROM NAME>"}}'`

Netcore Email API version of this call will be as follows (note: only API Key and endpoint URL is changed):

curl --request POST \
--url https://sgapi.netcorecloud.net/v3/mail/send \
--header 'authorization: Bearer <YOUR Netcore Email API KEY>' \
--header 'content-type: application/json'  \
--data '{"personalizations":[{"to":[{"email":"<RECIPIENT EMAIL ID>","name":"<RECIPIENT NAME>"}],"subject":"This is a test mail"}],"content": [{"type": "text/plain", "value": "Hello, How are you?"}],"from":{"email":"<FROM EMAIL ID>","name":"<FROM NAME>"}}'`

For the detailed list of Error codes, please refer this link.

You can also choose to integrate with Netcore Email API directly without using this migration API too. Explore our native API or our easy to integrate SDKs on GitHub.