Skip to main content

Create a Mailbox

Create and configure a new ECGrid mailbox to establish a dedicated EDI message queue for a company, division, or trading partner group.

Overview​

A mailbox is the core unit of EDI message routing in ECGrid. Each mailbox holds an inbox and outbox, is associated with one or more ECGrid IDs (ISA sender/receiver identifiers), and has its own access controls. Creating a mailbox involves three steps: provisioning the mailbox, verifying it was created correctly, and optionally applying configuration settings such as delete-on-download or inbox timeout rules.

Sequence:

  1. Create the mailbox with POST /v2/mailboxes/create.
  2. Retrieve the new mailbox record with GET /v2/mailboxes/{id} to verify.
  3. Optionally update mailbox configuration with POST /v2/mailboxes/update-config.

REST​

Auth: X-API-Key: <key> header

Step 1 — Create the mailbox​

POST https://rest.ecgrid.io/v2/mailboxes/create
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "networkId": 0,
  "uniqueId": "ACME-EDI-01",
  "companyName": "Acme Corporation",
  "mailboxConfig": {
    "deleteOnDownload": false,
    "inBoxTimeout": 72
  }
}
FieldTypeRequiredDescription
networkIdintegerNoParent network ID. Pass 0 to use the network associated with the API key.
uniqueIdstringYesA unique identifier for this mailbox within the network (alphanumeric, no spaces).
companyNamestringYesHuman-readable company or division name for this mailbox.
mailboxConfig.deleteOnDownloadbooleanNoIf true, parcels are automatically removed from the inbox after download confirmation. Default: false.
mailboxConfig.inBoxTimeoutintegerNoHours before an undownloaded parcel triggers an alert. Common values: 24, 48, 72.

Response:

{
  "success": true,
  "data": {
    "mailboxId": 54321,
    "networkId": 1001,
    "uniqueId": "ACME-EDI-01",
    "companyName": "Acme Corporation",
    "status": "Active",
    "createdDate": "2026-05-07T10:00:00Z"
  }
}

Record the mailboxId — you will need it for all subsequent API calls targeting this mailbox.

Step 2 — Verify the mailbox​

GET https://rest.ecgrid.io/v2/mailboxes/54321
X-API-Key: YOUR_API_KEY

Confirm that status is "Active" and all fields match your input.

Step 3 — (Optional) Update mailbox configuration​

Use POST /v2/mailboxes/update-config to adjust settings after creation, such as X12 delimiter preferences or inbox timeout values.

POST https://rest.ecgrid.io/v2/mailboxes/update-config
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "mailboxId": 54321,
  "inBoxTimeout": 48,
  "deleteOnDownload": true
}

Code Examples​

// .NET 10 — create and verify a mailbox using IHttpClientFactory (registered as "ECGrid")
// API key loaded from IConfiguration — never hardcoded

using System.Net.Http.Json;

public record CreateMailboxRequest(
    int NetworkId,
    string UniqueId,
    string CompanyName);

public record MailboxInfo(
    int MailboxId,
    int NetworkId,
    string UniqueId,
    string CompanyName,
    string Status,
    DateTimeOffset CreatedDate);

public record ApiResponse<T>(bool Success, T Data);

public class ECGridMailboxService
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<ECGridMailboxService> _logger;

    public ECGridMailboxService(
        IHttpClientFactory httpClientFactory,
        ILogger<ECGridMailboxService> logger)
    {
        _httpClientFactory = httpClientFactory;
        _logger = logger;
    }

    /// <summary>
    /// Creates a new ECGrid mailbox and returns the provisioned mailbox info.
    /// </summary>
    public async Task<MailboxInfo> CreateMailboxAsync(
        string uniqueId,
        string companyName,
        int networkId = 0,
        CancellationToken cancellationToken = default)
    {
        var http = _httpClientFactory.CreateClient("ECGrid");

        var request = new CreateMailboxRequest(networkId, uniqueId, companyName);

        var response = await http.PostAsJsonAsync(
            "/v2/mailboxes/create", request, cancellationToken);
        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<ApiResponse<MailboxInfo>>(cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("Empty response from mailbox create.");

        _logger.LogInformation(
            "Mailbox created: ID={MailboxId}, UniqueID={UniqueId}",
            result.Data.MailboxId, result.Data.UniqueId);

        // Verify the mailbox is reachable
        var verify = await http.GetFromJsonAsync<ApiResponse<MailboxInfo>>(
            $"/v2/mailboxes/{result.Data.MailboxId}", cancellationToken)
            ?? throw new InvalidOperationException("Could not verify mailbox after creation.");

        if (verify.Data.Status != "Active")
            _logger.LogWarning("Mailbox {Id} status is {Status} — expected Active.",
                verify.Data.MailboxId, verify.Data.Status);

        return verify.Data;
    }
}

Registration in Program.cs:

builder.Services.AddHttpClient("ECGrid", client =>
{
    client.BaseAddress = new Uri("https://rest.ecgrid.io");
    client.DefaultRequestHeaders.Add(
        "X-API-Key",
        builder.Configuration["ECGrid:ApiKey"]);
});

builder.Services.AddScoped<ECGridMailboxService>();

SOAP​

:::caution Established API The SOAP API is in maintenance mode. For new integrations use REST above. :::

Method: MailboxAdd(SessionID, NetworkID, UniqueID, CompanyName, ...)

Step 1 — Log in and get a session ID​

var loginResult = await client.LoginAsync(username, password);
string sessionId = loginResult.LoginResult;

Step 2 — Create the mailbox with MailboxAdd​

var result = await client.MailboxAddAsync(
    sessionId,
    networkId:   0,               // 0 = network associated with session
    uniqueId:    "ACME-EDI-01",
    companyName: "Acme Corporation");

int newMailboxId = result.MailboxAddResult.MailboxID;
Console.WriteLine($"New mailbox ID: {newMailboxId}");

Step 3 — Apply configuration with MailboxConfig​

await client.MailboxConfigAsync(
    sessionId,
    mailboxId:       newMailboxId,
    deleteOnDownload: false,
    inBoxTimeout:    72);

Code Examples​

// .NET 10 — dotnet-svcutil generated proxy
// Reference: https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx?WSDL

using ECGridOS;

var binding  = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
var endpoint = new EndpointAddress("https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx");
var client   = new ECGridOSAPIClient(binding, endpoint);

string sessionId = string.Empty;

try
{
    var loginResult = await client.LoginAsync(
        Environment.GetEnvironmentVariable("ECGRID_USER")!,
        Environment.GetEnvironmentVariable("ECGRID_PASS")!);
    sessionId = loginResult.LoginResult;

    // Create the mailbox
    var addResult = await client.MailboxAddAsync(
        sessionId,
        networkId:   0,
        uniqueId:    "ACME-EDI-01",
        companyName: "Acme Corporation");

    int mailboxId = addResult.MailboxAddResult.MailboxID;
    Console.WriteLine($"Mailbox created: ID={mailboxId}");

    // Apply configuration
    await client.MailboxConfigAsync(
        sessionId,
        mailboxId:        mailboxId,
        deleteOnDownload: false,
        inBoxTimeout:     72);

    Console.WriteLine("Mailbox configuration applied.");
}
finally
{
    if (!string.IsNullOrEmpty(sessionId))
        await client.LogoutAsync(sessionId);
}

:::tip Next Step After creating a mailbox, assign at least one ECGrid ID to it. See Onboard a Trading Partner for the full flow including ECGrid ID creation. :::