{"id":16116,"date":"2021-03-23T08:28:07","date_gmt":"2021-03-23T08:28:07","guid":{"rendered":"https:\/\/www.gmass.co\/blog\/?p=16116"},"modified":"2023-02-06T23:12:31","modified_gmt":"2023-02-06T23:12:31","slug":"gmass-api","status":"publish","type":"post","link":"https:\/\/www.gmass.co\/blog\/gmass-api\/","title":{"rendered":"How to use the GMass API"},"content":{"rendered":"

We’ve launched a beta version of the GMass API<\/a> that can handle basic GMass functionality around creating lists and sending campaigns. Over time, we’ll be adding more functionality, like accessing reporting data.<\/p>\n

Our API is the only API we know of that allows you to completely create and send a cold email campaign all from within the API, without ever having to do anything in the user interface.<\/div>\n

Getting Started<\/h2>\n

All endpoints begin with https:\/\/api.gmass.co\/api\/<\/strong>. The API is mostly RESTful and conforms to OpenAPI standards. To get started with the API:<\/p>\n

    \n
  1. Create an API Key in your Dashboard<\/a>. Go to the “API Keys” section.<\/li>\n
  2. Visit the API homepage<\/a>, which serves as a reference for all API methods<\/strong>.<\/li>\n
  3. You can perform a test API call to retrieve all the Google Sheet titles in your account with this URL: https:\/\/api.gmass.co\/api\/sheets?apikey=your-api-key<\/strong><\/li>\n
  4. You can access test forms<\/strong> for all methods using our Swagger-generated site here<\/a>. Note that the Swagger site does include descriptions of methods, but the more comprehensive documentation is at https:\/\/api.gmass.co\/docs<\/a>.<\/li>\n<\/ol>\n

    Authentication<\/h2>\n

    You can authenticate into the API using your API key and passing it either:<\/p>\n

      \n
    1. Via the query string as “apikey”<\/li>\n
    2. Via an HTTP header using X-apikey<\/li>\n<\/ol>\n

      Note that it must be passed as “apikey” and not any other variation of that. api-key and api_key will not work.<\/p>\n

      How to send a campaign<\/h2>\n

      The basic steps of sending a campaign through the API are similar to the steps you would take in the Gmail interface with the Chrome extension.<\/p>\n

        \n
      1. Determine the Google Sheet and the corresponding Worksheet that your email list is in using the \/api\/sheets<\/strong> and api\/sheets\/{sheetid}\/worksheets<\/strong> endpoints.<\/li>\n
      2. Create a GMass list address (for example: 10-recipients-akejflaek3@gmass.co) using the \/api\/lists<\/strong> endpoint, in which you’ll use the spreadsheetId<\/strong> and worksheetId<\/strong> from step 1.<\/li>\n
      3. Create a campaign DRAFT using the \/api\/campaigndrafts<\/strong> endpoint. You can add CC and BCC addresses here, as well as file attachments. This will return a Gmail DRAFT Id, which you can then use to send a campaign.<\/li>\n
      4. Send the campaign with the \/api\/campaigns<\/strong> endpoint and pass in the Gmail DRAFT Id from step 3, plus other campaign settings.<\/li>\n<\/ol>\n

        You can store the GMass alias addresses and reuse them in campaigns, and thereby skip steps 1 and 2 most of the time.<\/p>\n

        We’ll be adding endpoints, functionality, and better documentation with time.<\/p>\n

        What else can you do?<\/h2>\n

        Retrieve a list of all your campaigns using the campaigns<\/a> method.<\/p>\n

        Retrieve the lists of recipients<\/a>, opens<\/a>, clicks<\/a>, replies<\/a>, unsubscribes<\/a>, and bounces<\/a> for a particular campaign.<\/p>\n

        Send a transactional email<\/a> through your Google account. You can view a log of your transactional emails inside your dashboard<\/a>.<\/p>\n

        Error handling<\/h2>\n

        All calls to the API will return an HTTP 200 OK<\/strong> status code if the method call is successful<\/strong>.<\/p>\n

        If you don’t get an HTTP 200 OK status code, your code can assume there has been an error. Error codes include:<\/p>\n