Sendgrid Contacts API  Examples

Sendgrid Contacts API Examples


If you are using Sendgrid to send your Marketing / Promotional emails then using the Sendgrid Contacts API can automate quite a few things for you. Here are some simple API examples to add/remove/edit recipients to the Sendgrid Contacts Database and synchronising the Sendgrid lists with the WordPress mailing lists.

There are 2 ways to synchronise your mailing lists in wordpress with the Sendgrid lists. One is using the daily/weekly cron job and the other is through real time i.e. an on demand system.

Obviously we all would prefer the real time system. However it largely depends on how you handle your subscription process in WordPress.

  • If you have created your own subscription system then you are either storing the contacts in your own table or you are using the WordPress usermeta table. API can be called by making the necessary changes in your system. Synchronisation of the mailing lists in that case can be done in real time.
  • If you are using some plugin which offers hooks on various actions like
    • user subscription,
    • user confirmation/verification,
    • user unsubscription,

    simply use this hooks to provide real time synchronization by adding necessary code in functions.php.

  • However if you are using some wordpress plugin which does not offer hooks as mentioned above then the only option is using cron job.

Here are some Sendgrid Contacts API PHP examples. They show how to synchronize receipients on your existing mailing list with Sendgrid.

Here is the official documentation on Sendgrid API

Add New Recipient – Sendgrid Contacts API

Above code adds a new receipient to Sendgrid contacts Database. It does not add if the receipient already exits but in any case does return the Recipient ID of the recipient. Also the above code does not assign any lists to the contact. To assign some Sengrid list to the contact we need to know the recipient ID of the contact which Sendgrid returns after adding a new contact to the Database. Through the above code we get the receipient ID in the $receipient_id variable. You can store this variable within your wordpress table as you would need it  to perform the Sendgrid tasks related to the recipient whenever the contact gets edited within WordPress. If you do not store this variable in your wordpress table then you would need to execute above code each time for the contact you need to get the recipient ID.

Add Receipient to a particular list – Sendgrid Contacts API

Above function requires the ID of the Sendgrid List (SENDGRID_LIST_ID) to which the recipient needs to be added.

You can get the Sendgrid List ID from the Sendgrid interface. Just click on the list and you will notice the List ID in the URL

If you have added the receipient ID received from Sendgrid to your own table in WordPress then you will get it from there else you may need to run the Add new Recipient function again to get the receipient ID.

Remove/Delete recipient from a list – Sendgrid Contacts API

This function requires Sendgrid List ID and the Recipient ID as input. It removes the receipient from a particular list. It does not delete the recipient from the Sendgrid Contacts Database.

Prevent your emails going to spam/junk

Photo credit 11183232994 suicidexking

Emails going to spam folder can be a sticky issue and generally there is no simple way to fix the problem. If you are already facing this issue then either your domain is blacklisted somewhere or you may just be missing a few simple tricks.

In any case a preliminary check should be to check if your sending domain or your IP is blacklisted. This would be a preliminary check because if you are already blacklisted then no matter what efforts you make to fix other things your emails will still end up going to spam / junk folder.

Check if your site is blacklisted using below tools by adding your site domain or IP address. If you are using cloudflare then try both i.e. your site domain and then your site IP address. This is because if you are using cloudflare, a domain check may not resolve to the true IP of your site.

If your site is blacklisted you will need to request to have the mail server’s IP address delisted from any blacklists that it’s currently on.

Here’s a guide on how to get your IP delisted from a particular blacklist

If your site is not blacklisted then its half the good news for you. Below steps would fix most of the issues.

Check your email headers

All your domain emails should have SPF and DKIM records and they should be properly configured through your DNS settings. Both these records should show up as pass in your email headers.

One way to check your email headers is to send an email through your domain to one of the gmail addresses, open the email, click on the down arrow next to the “Reply” button, and select show original which will open a new tab with the email headers printed on top. On this page, if you see “signed-by: your domain name” then your DKIM signature is configured properly.

If you are on shared host, mostly these records are set up correctly and you won’t have to do anything. If they are not set up properly i.e. if they show up as fail or with some other status message you can request your hosting provider to set them up correctly. However please note that if you are on a shared host you are sharing the IP address with a few other sites. If any of the other sites/domains are blacklisted or are involved in some form of spamming it directly affects the IP and thus it affects the emails sent through your domain.

Double opt-in

Do no add any email addresses to your mailing list without verifying them i.e. always try to have a doubte opt-in method. The double opt-in confirms that the person who entered their email address actually wants to subscribe to the list. This can be easily achived by sending a verification email to the email address entered by the user.

Easy opt-out

Each email sent by you should have an unsubscribe link easily visible/prominent within the email. If users do not find this link they are more likely to get frustrated and mark your email as Spam or even Report Abuse. Since such users are never going to read your emails anyway it is better to provide them with an easily accessible Unsubscribe option.

Clear communication

It is a good policy to tell your users about the frequency of emails they will be getting from you. If for some reason you change the frequency, it is better to inform your users beforhand and to review their subscriptions. Such communciation only helps in building trust. If someone opts out due to such communication it will only help to filter your database to keep quality contacts.

Bulk mail sender

Sometimes either Gmail, Yahoo or Hotmail may block or mark all your emails as spam. It is very easy to identify this issue. If most of your Gmail users are registering but they are not verifying their accounts that means it is likely that Gmail is marking your emails as spam. This could be for number of reasons. One reason could be Gmail does not recognise you as a Bulk mail sender so when it receives lot of emails from your domain within a short period of time it thinks that you are spamming. In that case it is important to tell Gmail that you are a bulk mail sender by filling Bulk sender contact form

House keeping

Try to make some automation or regularly monitor your mailing list to keep it clean

  1. Automatically unsubscribe users whose addresses keep bouncing. Hard bounces can be removed straightaway while soft bounces can be monitored a few times.
  2. Remove users from your database who have marked youe emails as spam

Email Transaction system

It is good practice to use some form of email transactional system like Sendgrid, Mailgun, etc

Such systems are very easy to configure and they provide all the necessary information about how your emails are performing i.e.

  1. Who is reading your emails
  2. Which links are getting clicked
  3. Geographical data
  4. Who have marked your email as spam
  5. Hard and soft bounces, etc

Separate IP

If possible buy a separate IP for your site and accordingly choose a plan which allows you to host your site/sites on your own IP address (not shared with anyone else). This will allow you to keep the IP and your domain clean of blacklisting or spamming.



How to apply Sendgrid categories to WordPress emails

Sendgrid Categories

What are Sendgrid Email Categories

Creating categories for different kinds of emails sent through sendgrid is quite beneficial. It allows you to track emails based on each category i.e. it allows you to tag your emails by topics.

e.g. it would be nice to know

  • how many user registration emails actually were delivered,
  • how many people requested password resets, etc

For instance emails sent through wordpress can be categorised as

  1. User Registration
  2. Password Reset
  3. Newsletter, etc

How to add Sendgrid categories

As per the sendgrid documentation

You can add categories to the X-SMTPAPI header of the emails you send via SendGrid. This will allow you to track emails based on your own categorization system.

In case of wordpress emails here are the steps to follow

  1. Install the WordPress Sengrid plugin: Since the version 1.6.9 this plugin allows to add categories in the email headers.
  2. add the category headers to the wp_mail function as shown below

How to add category headers to the wp_mail function

The above headers can be added to your custom plugins where you define your own wp_mail function.

However in case of wordpress internal emails e.g. User Registration Confirmation email you would need to first customise that email to be able to add the required headers. For instance here is a nice link which shows how to customise User Registration Confirmation Emails

Sendgrid Category statistics

Once the required headers are added sengrid can shows statistics based on each sendgrid categories as shown below


Sendgrid Category statistics