How to Migrate from Sendgrid’s Mail Send API to Pepipost

As mentioned earlier it’s super easy to migrate from Sendgrid’s Mail Send API to Pepipost 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 Pepipost and you’re done.

Pepipost Migration API endpoint: https://sgapi.pepipost.com/

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

Here’s an extensive list of Sendgrid’s APIs and it’s parameter which Pepipost supports:

Type: Email Send

Method: POST

Endpoint: /v3/mail/send

#List of Sendgrid parametersDescriptionSupported in Pepipost
Migration API or not?
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.emailEmail address of the person to whom you are sending an email.Yes
2
personalization.to.nameThe name of the person to whom you are sending an email.No
3
personalization.cc.emailEmail address of the recipient who will receive a copy of your email.Yes
4
personalization.cc.nameName of the recipient who will receive a copy of your email.No
5
personalization.bcc.emailThe email address of the person to whom you are sending an email in bcc.No
6
personalization.bcc.nameThe name of the person to whom you are sending an email in bcc.No
7
personalization.subjectThe subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310Yes
8
personalization.headersA 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, BCCYes
9
personalization.substitutionsA 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.Yes
10
personalization.custom_argsValues 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.No
13
personalization.send_atA unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden.No
14
from
15
from.emailThe email address of the person to whom you are sending an email.Yes
16
from.nameThe name of the person to whom you are sending an email.Yes
17
reply_to
18
reply_to.emailThe email address of the person to whom recipients are going to send replies to.Yes
19
reply_to.nameThe name of the person to whom recipients are going to send replies to.No
20
subjectYes
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.typeThe mime type of the content you are including in your email. For example, “text/plain” or “text/html”.No
23
content.valueThe actual content of the specified mime type that you are including in your email.Yes
Attachments
An array of objects in which you can specify any attachments you want to include.
25
attachments.contentThe Base64 encoded content of the attachment.Yes
26
attachments.typeThe mime type of the content you are attaching. For example, “text/plain” or “text/html”.No
27
attachments.filenameThe filename of the attachment.Yes
28
attachments.dispositionThe 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).Yes
29
attachments.content_idThe 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.No
30
template_idThe 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.Yes
31
sectionsAn object of key/value pairs that define block sections of code to be used as substitutions. The key/value pairs must be strings.No
32
headersAn 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.No
33
categoriesAn array of category names for this message. Each category name may not exceed 255 characters.No
34
custom_argsValues 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.No
35
send_atA 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.No
36
batch_idThis 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.htmlNo
asm
An object allowing you to specify how to handle unsubscribes.
38
asm.group_idThe unsubscribe group to associate with this email.No
39
asm.groups_to_displayAn array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.No
40
ip_pool_nameThe IP Pool that you would like to send this email from.No
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.enableThis 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.No
43
mail_settings.bcc.emailThe email address that you would like to receive the BCC.Yes
44
mail_settings.bypass_list_management.enableAllows 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.No
45
mail_settings.footer.enableIndicates if this setting is enabled.Yes
46
mail_settings.footer.textThe plain text content of your footer.No
47
mail_settings.footer.htmlThe HTML content of your footer.No
48
mail_settings.sandbox_mode.enableThis allows you to send a test email to ensure that your request body is valid and formatted correctly.

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

Indicates if this setting is enabled.
No
50
mail_settings.spam_check.thresholdThe 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.No
51
mail_settings.spam_check.post_to_urlAn Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to.No
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.enableAllows you to track whether a recipient clicked a link in your email.

Indicates if this setting is enabled.
Yes
54
tracking_settings.click_tracking.enable_textIndicates if this setting should be included in the text/plain portion of your email.No
55
tracking_settings.open_tracking.enableAllows 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.Yes
56
tracking_settings.open_tracking.substitution_tagAllows 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.No
57
tracking_settings.subscription_tracking.enableAllows 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.
No
58
tracking_settings.subscription_tracking.htmlText to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>No
59
tracking_settings.subscription_tracking.textHTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>No
60
tracking_settings.subscription_tracking.substitution_tagA 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.No
61
tracking_settings.ganalytics.enableAllows you to enable tracking provided by Google Analytics. Indicates if this setting is enabled.No
62
tracking_settings.ganalytics.utm_sourceName of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)No
63
tracking_settings.ganalytics.utm_mediumName of the marketing medium. (e.g. Email)No
64
tracking_settings.ganalytics.utm_contentUsed to identify any paid keywords.No
65
tracking_settings.ganalytics.utm_termUsed to differentiate your campaign from advertisements.No
66
tracking_settings.ganalytics.utm_campaignThe name of the campaign.No

What will happen if a unsupported parameter is passed to Pepipost?

Pepipost 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 Pepipost, then please contact our Technical Support team on support@pepipost.com

How to use Pepipost migration APIs?

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

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

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 Pepipost 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 Pepipost’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 Pepipost’s key. Also, change the Sendgrid’s API endpoint mentioned in your code with that of Pepipost.

Sendgrid’s endpoint: https://api.sendgrid.com/v3/ to be changed with Pepipost’s migration API endpoint: https://sgapi.pepipost.com/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>"}}'`

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

curl --request POST \
--url https://sgapi.pepipost.com/v3/mail/send \
--header 'authorization: Bearer <YOUR PEPIPOST 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 Pepipost directly without using this migration API too. Explore our native API or our easy to integrate SDKs on GitHub.