API Access Tutorial

Welcome to our API! You can extract specific fields from email messages using our service. All API calls require an API key, which you can obtain by purchasing a subscription from our platform.

API Key Usage

Your API key is an AWS API Gateway key, which adds a layer of security and reliability by using Amazon Web Services. To use your API key, include it in the headers of your POST requests under the key x-api-key. Example:

Headers:
{
  "x-api-key": "your_aws_api_gateway_key"
}

To make a POST request to our API, use the following endpoint:

Endpoint: https://api.semantic9.com/email

Parameters to provide:

email: The full email instance (not just the body), converted to text.
list_of_values_to_extract (optional): A list of fields to extract from the email. If not provided, the default list will be used.
If you don't provide a list of fields, the following default list will be used:

['first_name', 'last_name', 'gender', 'company', 'email', 'phone_number', 'address', 'city', 'state', 'zip_code', 'country', 'contact_job_title', 'linked_in_profile', 'company_web_site', 'message_date']

The response format when using the default fields will be as shown below:

{
  "first_name": "John",
  "last_name": "Doe",
  "gender": "Male",
  "company": "Example Inc.",
  "email": "john@example.com",
  "phone_number": "+1-234-567-8900",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94105",
  "country": "USA",
  "contact_job_title": "Software Engineer",
  "linked_in_profile": "https://linkedin.com/in/johndoe",
  "company_web_site": "https://example.com",
  "message_date": "2024-10-16"
}

Examples in Different Programming Languages

Here are code examples to make API calls in different programming languages, including the use of your API key:

Python
JavaScript
Java
Ruby
C#

Python

import requests

url = "https://api.semantic9.com/email"
headers = {
    "x-api-key": "your_aws_api_gateway_key"
}

from email import message_from_string

email_instance = "Use mailbox module read and provide an instance of an email"
email_string = email_instance.as_string()

data = {
    "email": email_string,
    "list_of_values_to_extract": ["first_name", "last_name", "email"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

fetch('https://api.semantic9.com/email', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_aws_api_gateway_key'
    },
    body: JSON.stringify({
        email: 'email_text_content',
        list_of_values_to_extract: ['first_name', 'last_name', 'email']
    })
})
.then(response => response.json())
.then(data => console.log(data));

Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;

public class ApiClient {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://api.semantic9.com/email");
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setRequestProperty("x-api-key", "your_aws_api_gateway_key");
        connection.setDoOutput(true);

        String jsonInputString = "{\"email\": \"email_text_content\", \"list_of_values_to_extract\": [\"first_name\", \"last_name\", \"email\"]}";

        try (OutputStream os = connection.getOutputStream()) {
            byte[] input = jsonInputString.getBytes("utf-8");
            os.write(input, 0, input.length);
        }

        // Handle response here
    }
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.semantic9.com/email')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/json', 'x-api-key' => 'your_aws_api_gateway_key' })
request.body = { email: 'email_text_content', list_of_values_to_extract: ['first_name', 'last_name', 'email'] }.to_json

response = http.request(request)
puts response.body

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var client = new HttpClient();
        var json = "{\"email\": \"email_text_content\", \"list_of_values_to_extract\": [\"first_name\", \"last_name\", \"email\"]}";

        var content = new StringContent(json, Encoding.UTF8, "application/json");
        client.DefaultRequestHeaders.Add("x-api-key", "your_aws_api_gateway_key");

        var response = await client.PostAsync("https://api.semantic9.com/email", content);
        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}