SendGrid Migration Guide

 In Developer, Product

SendGrid migration to Pepipost – Is it complicated?

Switching from an ESP can seem like a daunting experience. There’s a lot of setup and configuration required. But it doesn’t have to be a nightmare. Not if you have a well-structured, easy to follow instructions that will guide you every step of the way. We’ve compiled a SendGrid Migration Guide that’ll make your move to Pepipost super easy and hassle free.

Before we get started, let’s first take a look at the different API terminologies between the two products.

SendGrid term Pepipost term
personalizations recipients
custom args attributes
categories tags
Domain whitelabel Sending domain

Migrating from SendGrid SMTP and SendGrid API

SendGrid Migration via SMTP API

Whether you are integrated with SendGrid via SMTP or API, this guide provides you with steps for easy SendGrid migration to Pepipost.

Set up your Pepipost account

You can start with Pepipost Forever Free plan (30,000 emails free per month, forever) or the Pro plan that offers additional features. Once you’ve chosen the plan, setting up your Pepipost account is just a two-step process:

  1. Signup and activate your account by clicking on the activation link received on your email.
  2. Configure the sender domain which you want to use for sending your emails.

Once the domain is verified and approved by our Compliance Team, you are all set to send emails from your Pepipost account.

Migrate your Suppression List

While at this point your account is ready to go live, we advise you to not migrate your email traffic immediately. First, make sure you have downloaded the blacklist/suppressed recipients from your Sendgrid account and uploaded the same on Pepipost. When switching email providers, it’s very important to avoid sending to emails to such recipients again as this can lead to very high bounce and complaint rates. High bounce and complaint rates can affect your email reputation, inbox delivery and may lead to suspension of your account.

Integrating the API

API End Point:

Sendgrid: POST HTTP/1.1

Sample SendGrid API v3 call:

“personalizations”: [
“to”: [
“email”: “”
“subject”: “Hello, World!”
“from”: {
“email”: “”
“content”: [
“type”: “text/plain”,
“value”: “Hello, World!”
] }

Pepipost: POST HTTP/1.1

POST /api/web.send.json HTTP/1.1
“fromname”:”sender name”,
“subject”:”test email subject”,
“replytoid”: “”,
“content”:”<p>Hi [%NAME%], This is a test email sent using Pepipost JSON/Email API</p>”
“tags”: “AccountDeactivation, Verification”,
“X-APIHEADER”: [“ID3″,”ID2”],
“AGE”:[“20″,”30”] },
“files”: {
“attachment_example1.txt”: “VGhpcyBpcyB0aGUgY29udGVudCBvZiBhIHRlc3QgZmlsZS4K”,
“attachment_example2.txt”: “VGhpcyBpcyB0aGUgY29udGVudCBvZiBhIHRlc3QgZmlsZSAyLgo=”

Example Response

HTTP/1.1 200 OK
{“message”:”SUCCESS”,”errorcode”: “0” ,”errormessage”:””}

Responses format

Name Description
message Its can have only 2 values – “SUCCESS” or “ERROR”
errorcode Pepipost API error code. Its value will be – 0 (zero) in case of success. In case of error it will be non-zero integer value.
errormessage Error specific error messages.

Here is a quick cheat chart to understand the terminology used in Sendgrid and its equivalent in Pepipost.

API Terminology

JSON Parameter Type Required Details Equivalent Pepipost parameter name
  • to       
array[object] Yes   recipients
·         email           
·         name optional     Not supported
  • cc        
      Not supported in API. But in SMTP you can do cc.
  • bcc     
·         email      
·         name       Not supported
  • subject           
·         headers       X-APIHEADER
·         substitutions optional     attributes
·         from       from
·         email             
·         name optional     Not supported
·         replyto       replytoid
·         email             
·         name       Not supported
·         subject       subject
·         content       content
·         type            Not supported
·         attachments       files
·         template_id       template
·         categories       tags
  • footer

How to Personalize emails?

SendGrid: personalizations >> substitutions

Pepipost: attributes

Personalizing your transactional emails is a very common requirement. Example: The template for the successful order placement email will be same for all your customers but different values need to be embedded inside the email to make it specific to each customer – like the name of the customer, details of the product purchased, product image and the amount paid.

In SendGrid, the personalization is done within the parameter “personalizations”, while in Pepipost the same is possible under the parameter “attributes”.

attributes is collection of key/value pairs. The data type is string and only underscore is allowed with no spaces.

SendGrid example on Personalization

“personalizations”: [{
“to”: [{
“email”: “”
“substitutions”: {
“%fname%”: “recipient”,
}] }

Pepipost example on Personalization


“AGE”:[“20″,”30”] }


How to track each email with some custom value which are internal to your organisation?

Sendgrid: X-SMTPAPI


Whether you are using SMTP or API, Pepipost has the same parameter for both X-APIHEADER can be used to pass your custom values to us. You can pass a JSON encoded data in this parameter. The X-APIHEADER that you add will be stripped from the final email. So you can expect to not actually see these headers in the final email.

Sendgrid example of passing a custom tracking value in API:

“unique_args”: {
“invoice_id”: [
] }

Pepipost example of passing a custom tracking value in API:


“X-APIHEADER”: [“{“invoice_id”:”23274221”}”,”{“invoice_id”:”81742290”}”]


How to tag emails under various categories/groups?

Tagging your Pepipost emails lets you easily search activity, compare stats, and more. Some examples of Tags are: “Invoice Emails”, “Forgot Password/OTP”, “Newsletters” etc. Add tags to emails while sending emails through API or SMTP.

Usage SendGrid Pepipost
In API category tags
In SMTP X-SMTPAPI: {“category”: [“ForgotPassword”,”Trans”]} X-TAGS:””ForgotPassword”,”Trans”

SendGrid: category

Pepipost: In API:tags

Sendgrid example of passing category value in API:

“category”: [
“Forgot Password”,
] }

Pepipost example of passing category value in API:

“tags”: “Forgot Password,Transactional”
] }

Important Note: Before running your first test email through Pepipost API, you need to ensure that your sender domain is configured and approved under your Pepipost Account. This is similar to how you whitelist domains in Sendgrid.

Just pick any of your favorite SDK from below and get started with Pepipost. Explore our complete API documentation.

  • PHP
  • Python
  • Ruby
  • NodeJS
  • NodeJS – Nodemailer
  • Java
  • Perl
  • C#

You can try every endpoint in the Pepipost API right from your browser using our Live API Explorer. There’s no longer a need to run cURL commands in terminal to test things out (though it’s totally fine if that’s your preference).

At Pepipost we believe in keeping things simple and easy. Should you still face trouble in SendGrid migration or have any queries, just reach out to us on our 24X7 live chat support and our developer evangelists will be happy to walk you through the migration process. Alternatively, you may also write to


Found This Blog Interesting Please Rate This Blog 1 Star2 Stars3 Stars4 Stars5 Stars (No Ratings Yet)
Recommended Posts
Showing 2 comments

Leave a Comment

We are always looking for fresh talent to contribute to our blog. If you have a knack for writing and a passion for email marketing, we would love to have your post on our Guest Blog .

Submit a Guest Post
Pepi thinking

Start typing and press Enter to searchi

Fill out your information below, and we will send you a PepiAlert, that will describe your domain’s email deliverability situation. Please note that your email address must match the domain, or the domain must be owned by the company matching the email address. We have the right to refuse the request, if we can’t verify the information.

*All fields are required