Developer Documentation

SUMail API for Educational Institutions

Issue and verify blockchain-based academic transcripts with just a few lines of code

2 seconds
Average API response
REST API
Simple integration
99.9%
Uptime SLA

🚀 Quick Start

1

Get Your API Key

Register your institution and generate API credentials

Request API Access →
2

Install SDK (Optional)

npm install @sumail/sdk
pip install sumail-sdk
3

Issue Your First Transcript

Use our API to mint blockchain-verified transcripts

💻 Code Examples

JavaScript / Node.js

const axios = require('axios');

const SUMAIL_API_KEY = process.env.SUMAIL_API_KEY;
const BASE_URL = 'https://api.sumail.xyz/v1';

async function issueTranscript(studentAddress, transcriptData) {
  const response = await axios.post(
    `${BASE_URL}/transcripts/issue`,
    {
      studentAddress,
      transcript: transcriptData,
      metadata: {
        issueDate: new Date().toISOString(),
        issuerName: 'Your University',
        issuerDomain: 'university.edu'
      }
    },
    {
      headers: {
        'Authorization': `Bearer ${SUMAIL_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Token ID:', response.data.tokenId);
  console.log('Verification Key:', response.data.verificationKey);
  return response.data;
}

Python

import requests
import os

SUMAIL_API_KEY = os.getenv('SUMAIL_API_KEY')
BASE_URL = 'https://api.sumail.xyz/v1'

def issue_transcript(student_address, transcript_data):
    headers = {
        'Authorization': f'Bearer {SUMAIL_API_KEY}',
        'Content-Type': 'application/json'
    }

    payload = {
        'studentAddress': student_address,
        'transcript': transcript_data,
        'metadata': {
            'issuerName': 'Your University',
            'issuerDomain': 'university.edu'
        }
    }

    response = requests.post(
        f'{BASE_URL}/transcripts/issue',
        json=payload,
        headers=headers
    )

    data = response.json()
    print(f"Token ID: {data['tokenId']}")
    print(f"Verification Key: {data['verificationKey']}")
    return data

cURL

curl -X POST https://api.sumail.xyz/v1/transcripts/issue \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "studentAddress": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "transcript": {
      "studentInfo": {
        "name": "Alice Johnson",
        "studentId": "UNI-2021-12345",
        "email": "alice@university.edu"
      },
      "degree": {
        "type": "Bachelor of Science",
        "major": "Computer Science",
        "gpa": 3.92,
        "graduationDate": "2025-05-20"
      }
    },
    "metadata": {
      "issuerName": "Your University",
      "issuerDomain": "university.edu"
    }
  }'

📡 Core API Endpoints

POST

/transcripts/issue

Issue a new academic transcript to a student

POST

/transcripts/{tokenId}/supersede

Issue a corrected version of an existing transcript

GET

/transcripts/verify/{verificationKey}

Verify a transcript using the student's verification key

GET

/transcripts/{tokenId}

Retrieve on-chain record for a specific token

GET

/transcripts?issuer={address}

List all transcripts issued by your institution

✨ Key Features

🔒

Soulbound Tokens

Transcripts are non-transferable NFTs that can't be sold or forged

🔗

Version Chains

Corrections create new versions while preserving full audit trail

🔐

End-to-End Encryption

Student data encrypted with their public key - zero PII on-chain

Instant Verification

Anyone can verify authenticity in seconds, not days

🔄

Key Recovery

Help students recover transcripts to new wallets if they lose access

📊

Dashboard & Analytics

Monitor issued transcripts and verification requests

📚 Resources & Support

Ready to Get Started?

Join leading universities issuing blockchain-verified transcripts