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.

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